GitLab MCP Server
A community MCP server for GitLab — works with any GitLab tier (Free, Premium, Ultimate), no GitLab Duo required. PAT-based auth. Streamable HTTP and stdio transports.
npx @ttpears/gitlab-mcp-server
Field notes: Two session bugs that broke my GitLab MCP server explains the recursive close callback and stale HTTP session behavior behind the current lifecycle handling.
Choose your deployment
Solo IDE
Claude Code (recommended)
claude mcp add gitlab \
--env GITLAB_URL=https://gitlab.com \
--env GITLAB_TOKEN=glpat-your-pat \
-- npx -y @ttpears/gitlab-mcp-server
--scope controls where the configuration lives:
--scope local(default) — only this user, only this project--scope user— shared across all of your projects--scope project— written to.mcp.jsonin the project root, intended for team check-in
For team check-in, use a ${VAR} placeholder so the PAT itself stays out of git:
{
"mcpServers": {
"gitlab": {
"command": "npx",
"args": ["-y", "@ttpears/gitlab-mcp-server"],
"env": {
"GITLAB_URL": "https://gitlab.com",
"GITLAB_TOKEN": "${GITLAB_TOKEN}"
}
}
}
}
Each contributor exports GITLAB_TOKEN in their shell; Claude Code expands it on launch.
Cold start
If launching via npx adds noticeable latency, install once:
npm install -g @ttpears/gitlab-mcp-server
…and replace npx -y @ttpears/gitlab-mcp-server with gitlab-mcp-server in your config.
Claude Desktop
Option A — MCPB one-click install: download
gitlab-mcp-community-${VERSION}.mcpb from the
latest GitHub Release
and drag it onto the Claude Desktop window. Fill in your GitLab URL and a
Personal Access Token when prompted; the token is stored in your OS keychain.
Use a read_api-scoped PAT for read-only access, or an api-scoped PAT to
also allow writes (create_issue, create_merge_request, etc.).
Option B — manual config: add to claude_desktop_config.json:
{
"mcpServers": {
"gitlab": {
"command": "npx",
"args": ["-y", "@ttpears/gitlab-mcp-server"],
"env": {
"GITLAB_URL": "https://gitlab.com",
"GITLAB_TOKEN": "glpat-your-pat"
}
}
}
}
LibreChat — service-account reads
A read-only service token covers reads (so anyone in the workspace can ask
questions). Each user supplies their own PAT for writes through LibreChat's
customUserVars.
LibreChat's documented extension point is docker-compose.override.yml — the
fragments below assume you're adding gitlab-mcp there alongside LibreChat's
own api, mongodb, etc.
.env
GITLAB_URL=https://gitlab.example.com
GITLAB_READ_TOKEN=glpat-readonly-service-token # read_api scope only
Use https://gitlab.com for SaaS GitLab; use your own host for self-hosted.
docker-compose.override.yml
services:
gitlab-mcp:
image: ghcr.io/ttpears/gitlab-mcp:1.14.0
env_file:
- .env
networks:
- librechat
restart: unless-stopped
env_file reads GITLAB_URL and GITLAB_READ_TOKEN from .env. No port
mapping needed — LibreChat's api container reaches gitlab-mcp over the
shared librechat network. Add ports: ["8008:8008"] only if you need to
hit it from the host (e.g. for curl http://localhost:8008/health).
Then:
docker compose -f docker-compose.yml -f docker-compose.override.yml up -d gitlab-mcp api
api is restarted alongside so it re-reads librechat.yaml.
librechat.yaml
mcpServers:
gitlab:
type: streamable-http
url: http://gitlab-mcp:8008/
startup: false # don't connect until the user supplies their PAT
initTimeout: 30000
timeout: 120000
headers:
Authorization: "Bearer {{GITLAB_PAT}}"
X-GitLab-Url: "{{GITLAB_URL_OVERRIDE}}" # only honored when GITLAB_PIN_HOST=false (default pins to GITLAB_URL)
customUserVars:
GITLAB_PAT:
title: "GitLab Personal Access Token"
description: "Your GitLab PAT with api scope. Used for issues, MRs, and comments you create or edit."
GITLAB_URL_OVERRIDE:
title: "GitLab URL (optional)"
description: "Leave blank to use the workspace default. Override only if your account is on a different GitLab instance."
initTimeout / timeout are forgiving defaults for slower internal networks
and large schemas — drop them if SaaS GitLab feels snappy.
Server-side env vars use
${VAR}. Per-user vars use{{VAR}}. They are not interchangeable.
LibreChat — strict per-user
Every call must carry a user PAT. No service-account fallback. Reads as well as writes are gated on the user's token.
Add MCP Server (UI path — recommended)
-
Host gitlab-mcp somewhere LibreChat can reach. For a quick standalone host:
docker run -d --restart unless-stopped \ -p 8008:8008 \ -e GITLAB_URL=https://gitlab.example.com \ --name gitlab-mcp \ ghcr.io/ttpears/gitlab-mcp:1.14.0Or, when running alongside LibreChat in the same compose project, drop it into
docker-compose.override.yml(no token env vars):services: gitlab-mcp: image: ghcr.io/ttpears/gitlab-mcp:1.14.0 environment: GITLAB_URL: https://gitlab.example.com networks: - librechat restart: unless-stopped -
In LibreChat → MCP Servers → Add MCP Server:
- URL:
https://your-host/(orhttp://gitlab-mcp:8008/if same network) - Authentication: API Key → check User provides key → header format Bearer
- Save
- URL:
-
Each user fills in their PAT through the MCP Tool Select Dialog when configuring an agent.
librechat.yaml equivalent
mcpServers:
gitlab:
type: streamable-http
url: http://gitlab-mcp:8008/
startup: false
initTimeout: 30000
timeout: 120000
headers:
Authorization: "Bearer {{GITLAB_PAT}}"
customUserVars:
GITLAB_PAT:
title: "GitLab Personal Access Token"
description: "Your GitLab PAT with api scope."
The container needs no env-configured token at all in this mode — every
request is rejected unless Authorization: Bearer … is present.
Hosting for a remote LibreChat
The server speaks plain HTTP. For LibreChat-as-a-service or any cross-network deployment, terminate TLS at a reverse proxy. Common patterns:
-
Caddy — auto-TLS via Let's Encrypt:
mcp.example.com { reverse_proxy gitlab-mcp:8008 } -
Traefik — Docker labels on the
gitlab-mcpservice. -
Cloudflare Tunnel — no public IP needed; expose
gitlab-mcp:8008through the tunnel.
The Authorization and Mcp-Session-Id headers must pass through unchanged. Most defaults handle this fine.
OAuth for remote users
For a publicly hosted instance where each user signs in with their own GitLab identity — and modern MCP clients (Claude.ai, Claude Code) connect with no manual token setup — enable brokered OAuth 2.1. The server then acts as its own OAuth Authorization Server in front of GitLab:
- advertises Protected Resource Metadata (RFC 9728) and Authorization Server
Metadata (RFC 8414) at the standard
.well-knownendpoints, - supports Dynamic Client Registration (RFC 7591), so clients self-register,
- runs authorization-code + PKCE against both the MCP client and GitLab (dual-PKCE) behind one fixed GitLab callback,
- gates the MCP endpoints with bearer validation — unauthenticated requests get
401+WWW-Authenticatepointing at the resource metadata (the discovery trigger), - mints its own opaque tokens and keeps each user's GitLab token server-side (no token passthrough).
Setup
-
Register one GitLab application (instance/group/user → Applications):
- Redirect URI:
https://<your-host>/gitlab/callback - Scopes:
api(read + write) orread_api - Confidential: yes (recommended) → you get a client secret; or mark it public for PKCE-only.
- Redirect URI:
-
Run the server (HTTP mode) with no
GITLAB_TOKEN— identity comes from each user's OAuth login:MCP_TRANSPORT=http GITLAB_MCP_PORT=8008 \ GITLAB_URL=https://gitlab.example.com \ GITLAB_MCP_OAUTH=true \ MCP_SERVER_URL=https://gitlab-mcp.example.com \ GITLAB_OAUTH_CLIENT_ID=<application id> \ GITLAB_OAUTH_CLIENT_SECRET=<application secret> \ GITLAB_OAUTH_SCOPES=api \ npx -y @ttpears/gitlab-mcp-server -
Point an MCP client at
https://gitlab-mcp.example.com/— it discovers the metadata, registers, and walks the user through GitLab sign-in automatically.
MCP_SERVER_URL must be HTTPS (terminate TLS at your reverse proxy) and must
match the host the GitLab redirect URI is registered under. Token/registration
state is in-memory, so run a single instance (or add a shared store) per issuer.
How this differs from GitLab's official MCP server
GitLab ships an official MCP server (Beta) that requires Premium/Ultimate and GitLab Duo.
Choose this server for Free/CE, GraphQL flexibility, LibreChat multi-user, or brokered OAuth without GitLab Duo. Choose the official server for Premium+Duo with semantic code search.
Tools
Search & Discovery
Read Operations
Achievements
GitLab Achievements are available on all tiers when enabled on the instance (introduced behind a feature flag in 15.10, enabled by default in 19.2, generally available in 19.3). Writes require a full-access token and group Maintainer/Owner permissions.
IDs can be numeric or GitLab global IDs. list_achievements uses first, after, and fetchAll as above; fetchAll stops at first items. includeRecipients adds one page of active awards per achievement with its own pageInfo; it does not fetch every recipient. Use the returned award ID (userAchievementId) for precise revocation. The username lookup scans recipient pages, stops with an explicit error if the scan limit is reached, and requires an award ID when multiple active awards match.
GitLab may require recipient acceptance before an award appears on a profile and sends an award notification. Avatar uploads and user profile display/reordering are managed in GitLab. See GitLab Achievements documentation and the GraphQL mutation reference.
Write Operations (require user authentication)
Configuration
Environment variables
GITLAB_TOKEN and GITLAB_READ_TOKEN are mutually exclusive; setting both is a startup error.
Removed in 1.14.0
GITLAB_AUTH_MODE— the three-way enum is gone. Pick your deployment shape by which env var you set; see Choose your deployment.GITLAB_SHARED_ACCESS_TOKEN— rename toGITLAB_TOKEN(full access) orGITLAB_READ_TOKEN(read-only).
Old env vars trigger a deprecation warning at startup and are otherwise ignored.
Troubleshooting
"This operation requires authentication" / "Write operation requires a user token":
- For LibreChat: check the user filled in their PAT in the MCP Tool Select Dialog (or in their
customUserVars). - For Claude Code: confirm
GITLAB_TOKENis set in the MCP server'senvblock. - If you set
GITLAB_READ_TOKEN, write operations against it are rejected by design — supply per-call user creds for writes.
Connection issues with LibreChat:
type: streamable-http(notsse).- URL is the Docker service name (
http://gitlab-mcp:8008/), not localhost, when LibreChat and gitlab-mcp share a Docker network. docker logs gitlab-mcpshows session init and request lines.
Schema introspection failed:
- GitLab 12.0+ with GraphQL API enabled.
- Verify
GITLAB_URLis reachable from the container.
Debug logging:
NODE_ENV=development GITLAB_TOKEN=glpat-... npm start
Health check (HTTP mode):
curl http://localhost:8008/health
Changelog
See CHANGELOG.md. Releases before 1.14.0 are in
GitHub releases.
Runtime and MCP compatibility
Node.js 22 or later is required; the container uses Node.js 24 LTS. HTTP browser clients must use an allowed origin (MCP_ALLOWED_ORIGINS); public deployments should set MCP_SERVER_URL. Native clients without an Origin header continue to work. Tool execution and input-validation failures return isError: true with a text explanation. Object results include structuredContent alongside the JSON text for older clients.
