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

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

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.