GitLab MCP Server

A community MCP server for GitLab — works with any GitLab tier (Free, Premium, Ultimate), no GitLab Duo required.

npx @ttpears/gitlab-mcp-server

How This Differs from GitLab's Official MCP Server

GitLab ships an official MCP server (Beta) that requires Premium/Ultimate and GitLab Duo with beta features enabled. This community server is an alternative for teams that don't have those requirements or need different capabilities.

Choose this server if you're on GitLab Free/Community Edition, need GraphQL flexibility, want repo browsing, or run LibreChat multi-user deployments.

Choose the official server if you have GitLab Premium/Ultimate with Duo, need semantic code search, or prefer OAuth over PATs.

Quick Start

1. Create a GitLab Token

Go to GitLab → User Settings → Access Tokens → create a token with read_api (read-only) or api (full access) scope.

2. Choose Your Client

• Claude Code — stdio transport, single-user
• LibreChat (Docker) — streamable HTTP, multi-user with per-user auth

Claude Code

Add to your Claude Code settings (.claude/settings.json or project .mcp.json):

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@ttpears/gitlab-mcp-server"],
      "env": {
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_SHARED_ACCESS_TOKEN": "glpat-your-token-here"
      }
    }
  }
}

Restart Claude Code to load the server.

LibreChat (Docker)

Runs as a sidecar container using streamable HTTP transport for multi-user deployments with per-user credential isolation.

1. Add environment variables to your LibreChat .env:

GITLAB_URL=https://gitlab.com
GITLAB_AUTH_MODE=hybrid
GITLAB_SHARED_ACCESS_TOKEN=glpat-your-shared-token
GITLAB_MCP_PORT=8008
MCP_TRANSPORT=http

2. Add the service to docker-compose.override.yml:

services:
  gitlab-mcp:
    build:
      context: .
      dockerfile: Dockerfile.mcp-gitlab
    env_file:
      - .env
    ports:
      - "8008:8008"
    networks:
      - librechat
    restart: unless-stopped

Copy the Dockerfile from this repo into your LibreChat directory as Dockerfile.mcp-gitlab. It clones and builds from this repository automatically — no source files needed.

3. Configure in librechat.yml:

mcpServers:
  gitlab:
    type: streamable-http
    url: "http://gitlab-mcp:8008/"
    headers:
      Authorization: "Bearer {{GITLAB_PAT}}"
      X-GitLab-Url: "{{GITLAB_URL_OVERRIDE}}"
    customUserVars:
      GITLAB_PAT:
        title: "GitLab Personal Access Token"
        description: "PAT with api scope"
      GITLAB_URL_OVERRIDE:
        title: "GitLab URL (optional)"
        description: "e.g., https://gitlab.yourdomain.com"

4. Restart LibreChat:

docker compose down && docker compose -f docker-compose.yml -f docker-compose.override.yml up -d

Available Tools

Search & Discovery

Read Operations

Write Operations (requires user authentication)

Configuration

Authentication Modes

Environment Variables

Troubleshooting

Connection issues with LibreChat:

• Verify type: streamable-http in librechat.yml (not sse)
• URL should be http://gitlab-mcp:8008/ (the Docker service name, not localhost)
• Ensure both containers share the same Docker network
• Check logs: docker logs gitlab-mcp

Authentication errors:

• Verify token has read_api or api scope and hasn't expired
• For LibreChat: check the user provided a valid PAT in the credentials UI

Schema introspection failed:

• Requires GitLab 12.0+ with GraphQL API enabled
• Verify GITLAB_URL is reachable from the container

Debug logging:

NODE_ENV=development GITLAB_URL=https://your-gitlab.com npm start

Health check (HTTP mode):

curl http://localhost:8008/health

Testing

# Test with MCP Inspector
npx @modelcontextprotocol/inspector npx @ttpears/gitlab-mcp-server

Contributing

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

License

MIT