GitLab MCP

A Model Context Protocol server that exposes the GitLab REST API to MCP clients (Claude Code, Claude Desktop, etc.) to drive projects, issues, merge requests, repositories, and CI/CD pipelines.

The server is multi-tenant: it stores no credentials. Every caller supplies their own GitLab token and instance URL, so one deployed server can serve many users, each acting as themselves.

Authentication

Each request resolves credentials in this order:

1. HTTP headers (for networked transports — the normal case for a deployed server):
   • X-GitLab-Token: glpat-xxxx (or Authorization: Bearer glpat-xxxx)
   • X-GitLab-Url: https://gitlab.example.com (defaults to https://gitlab.com)
2. Environment variables (fallback, handy for local stdio use):
   • GITLAB_TOKEN, GITLAB_URL

Create the token in GitLab under Settings → Access Tokens with the api scope.

Setup

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Run

gitlab-mcp          # console script (installed by pip)
# or
python -m gitlab_mcp

The server speaks MCP over stdio.

Docker / deploy on a server

CI publishes an image to GitHub Container Registry on every push to main and on version tags:

docker pull ghcr.io/shahabmosavi/gitlab_mcp:main

Run it as a networked MCP server (HTTP transport). No token is baked in — callers authenticate per request with headers:

docker run -d --name gitlab-mcp -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  ghcr.io/shahabmosavi/gitlab_mcp:main

Env var	Default	Purpose
MCP_TRANSPORT	stdio	stdio, streamable-http, or sse
MCP_HOST	0.0.0.0	Bind host for networked transports
MCP_PORT	8000	Bind port for networked transports

Use with Claude Code

Connect to a deployed server (each user adds it with their own token/instance):

claude mcp add --transport http gitlab https://your-server:8000/mcp \
  --header "X-GitLab-Token: glpat-xxxxxxxx" \
  --header "X-GitLab-Url: https://gitlab.example.com"

Or run it locally over stdio (token via env, no headers needed):

claude mcp add gitlab --env GITLAB_TOKEN=glpat-xxxx --env GITLAB_URL=https://gitlab.example.com -- gitlab-mcp

(Use the absolute path to the gitlab-mcp binary inside .venv/bin/ if it isn't on your PATH.)

Tools

Area	Tools
Projects/Groups	list_projects, get_project, create_project, list_groups, list_group_projects
Issues	list_issues, get_issue, create_issue, update_issue, comment_issue, list_issue_notes
Merge requests	list_merge_requests, get_merge_request, get_merge_request_diffs, create_merge_request, update_merge_request, merge_merge_request, approve_merge_request, comment_merge_request, list_merge_request_notes
Repository	list_branches, create_branch, delete_branch, get_file, create_or_update_file, delete_file, list_repository_tree, list_commits, get_commit_diff, create_commit, list_tags, create_tag
CI/CD	list_pipelines, get_pipeline, create_pipeline, retry_pipeline, cancel_pipeline, list_pipeline_jobs, get_job_log
Misc	get_current_user, search_users, search
Escape hatch	gitlab_api — call any GitLab REST endpoint directly

Whatever isn't covered by a dedicated tool is reachable through gitlab_api, so the server can do anything your token is allowed to do.

Notes

• project_id accepts a numeric ID or a URL path like group/subgroup/project.
• Issues and merge requests are addressed by their project-scoped IID (the number in the web URL), not their global ID.
• List tools trim responses to the most useful fields to keep them compact; use gitlab_api when you need the full, raw payload.