mcp-gitlab

mcp-gitlab is a Model Context Protocol (MCP) server for the GitLab REST API that provides 76 tools, 6 resources, and 5 prompts for AI assistants to manage projects, merge requests, pipelines, CI/CD variables, approvals, issues, code reviews, and more. Works with Claude Desktop, Claude Code, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible client.

Built with FastMCP, httpx, and Pydantic.

1-Click Installation

💡 Tip: For other AI assistants (Claude Code, Windsurf, IntelliJ), visit the GitLab MCP Installation Gateway.

claude mcp add gitlab -- uvx mcp-gitlab

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

uv pip install mcp-gitlab

Configuration

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | GITLAB_URL | Yes | - | GitLab instance URL (e.g. https://gitlab.example.com) | | GITLAB_TOKEN | Yes | - | Authentication token (see below) | | GITLAB_READ_ONLY | No | false | Set to true to disable write operations | | GITLAB_TIMEOUT | No | 30 | Request timeout in seconds | | GITLAB_SSL_VERIFY | No | true | Set to false to skip SSL verification |

Supported Token Types

The server checks these environment variables in order — first match wins:

1. GITLAB_TOKEN
2. GITLAB_PAT
3. GITLAB_PERSONAL_ACCESS_TOKEN
4. GITLAB_API_TOKEN

These accept any of the following token types:

| Token Type | Format | Use Case | |------------|--------|----------| | Personal access token | glpat-xxx | User-level access with api scope | | OAuth2 token | oauth-xxx | OAuth app integrations | | CI job token | $CI_JOB_TOKEN | GitLab CI pipeline access |

Compatibility

| Client | Supported | Install Method | |--------|-----------|----------------| | Claude Desktop | Yes | claude_desktop_config.json | | Claude Code | Yes | claude mcp add | | Cursor | Yes | One-click deeplink or .cursor/mcp.json | | VS Code Copilot | Yes | One-click deeplink or .vscode/mcp.json | | Windsurf | Yes | ~/.codeium/windsurf/mcp_config.json | | Any MCP client | Yes | stdio or HTTP transport |

Tools (76)

| Category | Count | Tools | |----------|-------|-------| | Projects | 4 | get, create, delete, update merge settings | | Project Approvals | 10 | get/update config, CRUD approval rules (project + MR) | | Groups | 6 | list, get, share/unshare project, share/unshare group | | Branches | 3 | list, create, delete | | Commits | 4 | list, get (with diff), create, compare | | Merge Requests | 8 | list, get, create, update, merge, merge-sequence, rebase, changes | | MR Notes | 6 | list, add, delete, update, award emoji, remove emoji | | MR Discussions | 4 | list, create (inline + multi-line), reply, resolve | | Pipelines | 5 | list, get (with jobs), create, retry, cancel | | Jobs | 4 | retry, play, cancel, get log | | Tags | 4 | list, get, create, delete | | Releases | 5 | list, get, create, update, delete | | CI/CD Variables | 8 | CRUD for project variables, CRUD for group variables | | Issues | 5 | list, get, create, update, add comment |

Resources (6)

The server exposes curated workflow guides as MCP resources that clients can read on demand.

| URI | Name | Description | |-----|------|-------------| | resource://rules/gitlab-ci | GitLab CI/CD Pipeline Patterns | Stage design, job rules, caching, artifacts, needs DAG, multi-project pipelines | | resource://rules/git-workflow | Git Workflow Standards | Branch naming, trunk-based flow, merge vs rebase, protected branches | | resource://rules/mr-hygiene | Merge Request Best Practices | MR size, description templates, review checklists, thread resolution | | resource://rules/conventional-commits | Conventional Commits Spec | Commit types, scopes, breaking changes, changelog generation | | resource://guides/code-review | Code Review Standards | Review priorities, inline comments, approval workflows, nit vs blocker | | resource://guides/codeowners | GitLab CODEOWNERS Reference | Syntax, section owners, approval rules, pattern matching |

Prompts (5)

The server provides MCP prompts — reusable multi-tool workflow templates that clients can surface as slash commands.

| Prompt | Parameters | Workflow | |--------|-----------|----------| | review_mr | project_id, mr_iid | Fetch MR → check pipeline → review changes → write discussion notes | | diagnose_pipeline | project_id, pipeline_id | Fetch pipeline → identify failed jobs → get logs → suggest fix | | prepare_release | project_id, tag_name, ref | Compare commits since last tag → draft changelog → create tag + release | | setup_branch_protection | project_id | Review settings → configure merge method → set approval rules | | triage_issues | project_id, label | List open issues → categorize → prioritize → identify duplicates |

Usage Examples

Projects & Branches

"Get details for project my-org/api-gateway"
→ gitlab_get_project(project_id="my-org/api-gateway")

"Create a feature branch from main"
→ gitlab_create_branch(project_id="123", branch_name="feat/login", ref="main")

"Delete all branches merged into main"
→ gitlab_list_branches(project_id="123") → filter merged → gitlab_delete_branch for each

Merge Requests & Code Review

"Open a merge request from feat/login to main"
→ gitlab_create_mr(project_id="123", source_branch="feat/login", target_branch="main", title="Add login")

"Review MR !42 — list changes and add inline comments"
→ gitlab_mr_changes(project_id="123", mr_iid=42)
→ gitlab_create_mr_discussion(project_id="123", mr_iid=42, body="nit: ...", new_path="src/auth.py", new_line=15)

"Merge MR !42 after resolving all threads"
→ gitlab_list_mr_discussions(project_id="123", mr_iid=42) → resolve unresolved
→ gitlab_merge_mr(project_id="123", mr_iid=42, squash=True)

Pipelines & CI/CD

"Show failed pipelines on main this week"
→ gitlab_list_pipelines(project_id="123", ref="main", status="failed")

"Retry a failed pipeline"
→ gitlab_retry_pipeline(project_id="123", pipeline_id=456)

"Get the build log for job 789"
→ gitlab_get_job_log(project_id="123", job_id=789, tail_lines=100)

Issues

"Create a bug report in project 123"
→ gitlab_create_issue(project_id="123", title="Login page 500 error", labels=["bug","P1"])

"Find open issues assigned to me"
→ gitlab_list_issues(project_id="123", state="opened", assignee_username="johndoe")

Security Considerations

• Token scope: Use the minimum required scope. api scope grants full access; prefer read_api for read-only deployments.
• Read-only mode: Set GITLAB_READ_ONLY=true to disable all write operations (create, update, delete, merge). Read-only mode is enforced server-side before any API call.
• SSL verification: GITLAB_SSL_VERIFY=true by default. Only disable for self-signed certificates in trusted networks.
• CI/CD variable masking: gitlab_list_variables and gitlab_list_group_variables automatically mask values of variables marked as masked in GitLab, returning ***MASKED*** instead of the actual value.
• MCP tool annotations: Each tool declares readOnlyHint, destructiveHint, and idempotentHint for client-side permission prompts.
• No credential storage: The server does not persist tokens. Credentials are read from environment variables at startup.

Rate Limits & Permissions

Rate Limits

GitLab enforces per-user rate limits (default: 2000 requests/minute for authenticated users). When rate-limited, tools return a 429 error with a hint to wait before retrying. Paginated endpoints default to 20 results per page; use per_page (max 100) to reduce the number of API calls.

Required Permissions

| Operation | Minimum GitLab Role | |-----------|-------------------| | Read projects, MRs, pipelines, issues | Reporter | | Create branches, MRs, issues | Developer | | Merge MRs, manage CI/CD variables | Maintainer | | Delete projects, manage approval rules | Maintainer/Owner | | Share projects/groups | Owner (or Admin) |

CLI & Transport Options

# Default: stdio transport (for MCP clients)
uvx mcp-gitlab

# HTTP transport (SSE or streamable-http)
uvx mcp-gitlab --transport sse --host 127.0.0.1 --port 8000
uvx mcp-gitlab --transport streamable-http --port 9000

# CLI overrides for config
uvx mcp-gitlab --gitlab-url https://gitlab.example.com --gitlab-token glpat-xxx --read-only

The server loads .env files from the working directory automatically via python-dotenv.

Development

git clone https://github.com/vish288/mcp-gitlab.git
cd mcp-gitlab
uv sync --all-extras

uv run pytest --cov
uv run ruff check .
uv run ruff format --check .

License

MIT