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

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.json in 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

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}}"   # optional; lets a user point at a different GitLab
    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)

1. 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.0
   

   Or, 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
   

2. In LibreChat → MCP Servers → Add MCP Server:

   • URL: https://your-host/ (or http://gitlab-mcp:8008/ if same network)
   • Authentication: API Key → check User provides key → header format Bearer
   • Save

3. 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-mcp service.

• Cloudflare Tunnel — no public IP needed; expose gitlab-mcp:8008 through the tunnel.

The Authorization and Mcp-Session-Id headers must pass through unchanged. Most defaults handle this fine.

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, or LibreChat
multi-user. Choose the official server for Premium+Duo with semantic
code search, or if you prefer OAuth.

Tools

Search & Discovery

Read Operations

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 to GITLAB_TOKEN (full access) or GITLAB_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_TOKEN is set in the MCP server's env block.
• 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 (not sse).
• URL is the Docker service name (http://gitlab-mcp:8008/), not localhost, when LibreChat and gitlab-mcp share a Docker network.
• docker logs gitlab-mcp shows session init and request lines.

Schema introspection failed:

• GitLab 12.0+ with GraphQL API enabled.
• Verify GITLAB_URL is 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.

License

MIT