gitlab-mcp-server

GitLab MCP Server

A Model Context Protocol (MCP) server that exposes the entire GitLab API as MCP tools, resources, and prompts for AI assistants. Single static binary — zero dependencies.

Security first: Continuously monitored on SonarCloud with quality gates, coverage, and security scanning. Supports read-only mode, safe mode (dry-run preview), and self-hosted GitLab with TLS verification.

Highlights

• 1006 MCP tools — broad GitLab REST API v4 + GraphQL coverage across 162 domain sub-packages: projects, branches, tags, releases, merge requests, issues, pipelines, jobs, groups, users, wikis, environments, deployments, packages, container registry, runners, feature flags, CI/CD variables, templates, admin settings, access tokens, deploy keys, and more
• 32 meta-tools (47 with the Enterprise/Premium catalog) — domain-grouped dispatchers that reduce token overhead for LLMs (optional, enabled by default). 15 additional enterprise meta-tools available for Premium/Ultimate features
• 11 sampling actions — LLM-assisted code review, issue analysis, pipeline failure diagnosis, security review, release notes, milestone reports, and more via gitlab_analyze meta-tool (MCP sampling capability)
• 4 elicitation tools — interactive creation wizards (issue, MR, release, project) with step-by-step user prompts
• 46 MCP resources — read-only data: user, groups, group members, group projects, projects, issues, pipelines, members, labels, milestones, branches, MRs, releases, tags, commits, file blobs, wiki pages, MR notes, MR discussions, meta-tool JSON Schemas, single-entity templates (issue, MR, branch, tag, release, label, milestone, commit, wiki page, deployment, environment, job, board, snippet, deploy key, feature flag, group label, group milestone), workspace roots, and 5 workflow best-practice guides
• 38 MCP prompts — AI-optimized: code review, pipeline status, risk assessment, release notes, standup, workload, user stats, team management, cross-project dashboards, analytics, milestones, audit
• 6 MCP capabilities — logging, completions, roots, progress, sampling, elicitation
• 50 tool icons — base64-encoded SVG icons (Sizes: ["any"]) on all tools, resources, and prompts for visual identification in MCP clients
• Pagination on all list endpoints with metadata (total items, pages, next/prev)
• Transports: stdio (default for desktop AI) and HTTP (Streamable HTTP for remote clients)
• Cross-platform: Windows, Linux & macOS, amd64 & arm64
• Self-hosted GitLab with self-signed TLS certificate support

Example Prompts

Once connected, just talk to your AI assistant in natural language:

"List my GitLab projects" "Show me open merge requests in my-app" "Create a merge request from feature-login to main" "Review merge request !15 — is it safe to merge?" "List open issues assigned to me" "What's the pipeline status for project 42?" "Why did the last pipeline fail?" "Generate release notes from v1.0 to v2.0"

The server handles the translation from natural language to GitLab API calls. You do not need to know project IDs, API endpoints, or JSON syntax — the AI assistant figures that out for you. See Usage Examples for more scenarios.

Quick Start

1. Download

Download the latest binary for your platform from GitHub Releases and make it executable:

chmod +x gitlab-mcp-server-*  # Linux/macOS only

2. Configure your MCP client

Recommended: Run the built-in setup wizard — it configures your GitLab connection and MCP client in one step:

./gitlab-mcp-server --setup

Tip: The wizard supports Web UI, Terminal UI, and plain CLI modes. On Windows, double-click the .exe to launch the wizard automatically.

Or configure manually — expand your client below:

{
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

claude mcp add gitlab /path/to/gitlab-mcp-server \
  -e GITLAB_URL=https://gitlab.example.com \
  -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

{
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

{
  "context_servers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "args": [],
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "args": [],
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

3. Verify

Open your AI client and try:

"List my GitLab projects"

See the Getting Started guide for detailed setup instructions.

Tool Modes

Two registration modes, controlled by the META_TOOLS environment variable:

Meta-tool summary:

32 base / 47 with enterprise meta-tools. See Meta-Tools Reference for the complete list with actions and examples.

Compatibility

Tested with: VS Code + GitHub Copilot, Claude Desktop, Claude Code, Cursor, Windsurf, JetBrains IDEs, Zed, Kiro, Cline, Roo Code.

See the full Compatibility Matrix for detailed client support.

Documentation

Full documentation is available at jmrplens.github.io/gitlab-mcp-server.

Tech Stack

Building from Source

git clone https://github.com/jmrplens/gitlab-mcp-server.git
cd gitlab-mcp-server
make build

See the Development Guide for cross-compilation and contributing guidelines.

Docker

docker pull ghcr.io/jmrplens/gitlab-mcp-server:latest

# Single-instance mode (fixed GitLab URL for all clients)
docker run -d --name gitlab-mcp-server -p 8080:8080 \
  -e GITLAB_URL=https://gitlab.example.com \
  -e GITLAB_SKIP_TLS_VERIFY=true \
  ghcr.io/jmrplens/gitlab-mcp-server:latest

# Multi-instance mode (clients send GITLAB-URL header per request)
docker run -d --name gitlab-mcp-server -p 8080:8080 \
  ghcr.io/jmrplens/gitlab-mcp-server:latest

Clients authenticate via PRIVATE-TOKEN or Authorization: Bearer headers. In multi-instance mode, clients must also send a GITLAB-URL header to target a specific GitLab instance. See HTTP Server Mode and Docker documentation for Docker Compose and configuration options.

FAQ

Contributing

See CONTRIBUTING.md for development guidelines, branch naming, commit conventions, and pull request process.

Security

See SECURITY.md for the security policy and vulnerability reporting.

Code of Conduct

See CODE_OF_CONDUCT.md. This project follows the Contributor Covenant v2.1.