GitLab MCP Server

A community Model Context Protocol server that lets AI clients search GitLab, read repositories, review merge requests, manage issues, and summarize team activity. Supports GitLab.com and self-managed GitLab through stdio and Streamable HTTP.

This project is independent of GitLab Inc. It does not require GitLab Duo. Individual tools remain subject to your GitLab version, tier, enabled features, token scopes, and role.

Start locally

Requires Node.js 22 or later. CI covers Node.js 22 and 24; the container uses Node.js 24.

1. Create a GitLab personal access token with read_api for reads or api for reads and writes. The token can only access resources its owner is allowed to use.
2. Add this server to your client's MCP configuration. Replace the token locally; keep the resulting file out of version control.

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@ttpears/gitlab-mcp-server@4.0.0"],
      "env": {
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_READ_TOKEN": "glpat-replace-locally"
      }
    }
  }
}

3. Restart or reconnect the client. Ask it to call get_current_user, then search_projects with {"searchTerm":"your-project","first":5}.

For writes, replace GITLAB_READ_TOKEN with GITLAB_TOKEN and use an api-scoped token. Setting both variables is a startup error. Stdio is the default; it communicates over stdin/stdout and does not open a listening port.

Choose a setup

Use case	Setup
Claude Code, Claude Desktop, VS Code, or another local client	Client installation
Claude Desktop bundle	Download gitlab-mcp-community-4.0.0.mcpb from the 4.0.0 release
LibreChat with each user's PAT	LibreChat guide and YAML example
Shared remote server with GitLab sign-in	OAuth setup
Docker or a reverse proxy	Deployment and operations
Existing installation	Upgrade to 4.0

For a local HTTP smoke test without a shared token:

docker run --rm --name gitlab-mcp \
  -p 127.0.0.1:8008:8008 \
  -e GITLAB_URL=https://gitlab.com \
  ghcr.io/ttpears/gitlab-mcp:4.0.0

Connect an MCP client to http://localhost:8008/ and send Authorization: Bearer <your-GitLab-PAT> on every request. curl http://localhost:8008/health checks liveness. The published image currently targets Linux amd64. Configure HTTPS and user authentication before remote use; see the deployment guide.

What you can do

The server exposes 69 tools and 8 workflow prompts. The tool reference lists every tool, its input parameters, defaults, and write classification.

Task	Start with
Find projects, groups, users, issues, or merge requests	search_projects, search_groups, search_users, search_issues, search_merge_requests
Identify a path and inspect code	resolve_path, browse_repository, get_file_content
Review a change and its CI results	get_merge_request_context, get_merge_request_diffs, get_merge_request_pipelines, get_pipeline_jobs
Triage and update work	get_issue_context, create_issue, update_issue, create_note, update_merge_request
Work with planning and notifications	list_milestones, list_iterations, list_work_items, list_my_todos
Summarize activity and review delays	analytics_user_summary, analytics_group_summary, analytics_review_bottlenecks
Manage group achievements	list_achievements, create_achievement, award_achievement
Discover instance-specific API capabilities	get_available_queries, get_type_fields

Try: “Find open bugs assigned to me,” “Review MR !42 in group/project,” or “Summarize this group's activity since Monday.” See workflows and pagination for exact tool-call examples and prompt names.

Read before sharing a server

• GITLAB_TOKEN is a fallback for reads and writes. GITLAB_READ_TOKEN is a fallback for reads only. A shared fallback exposes that account's accessible data to callers using it.
• With neither fallback set, each operation needs user credentials through an HTTP PAT, OAuth, or userCredentials.
• Host pinning, finite resource limits, and restrictions on custom GraphQL/REST tools are enabled by default. Tool annotations are client hints; GitLab permissions and the server's credential checks enforce access.
• fetchAll: true fetches up to first items. For complete results, keep following each connection's pageInfo.endCursor while hasNextPage is true.

See authentication and security for credential precedence, OAuth consent, encrypted Redis storage, and access boundaries.

Documentation

• Installation and client configuration
• Authentication and security
• Deployment and operations
• Workflows, results, and pagination
• Environment variable reference
• Complete tool reference
• Troubleshooting
• Upgrading to 4.0
• Contributing and architecture
• Changelog · Releases · Issue tracker

Field notes: Two session bugs that broke my GitLab MCP server.

Licensed under MIT.