mcp-gitlab

<!-- mcp-name: io.github.vish288/mcp-gitlab -->

mcp-gitlab is a Model Context Protocol (MCP) server for the GitLab REST API that provides 83 tools, 7 resources, and 6 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.

Supports GitLab.com and self-hosted GitLab instances (CE/EE). No GitLab Duo or Premium required.

Built with FastMCP, httpx, and Pydantic.

Install: uvx mcp-gitlab | PyPI | MCP Registry | Changelog

1-Click Installation

💡 Tip: For other AI assistants (Claude Code, Windsurf, IntelliJ, Gemini CLI), visit the [GitLab MCP Installation Gateway](https://vish288.github.io/mcp-install?server=mcp-gitlab).

<details> <summary><b>Manual Setup Guides (Click to expand)</b></summary> <br/>

Prerequisite: Install uv first (required for all uvx install flows). Install uv.

Claude Code

claude mcp add gitlab -- uvx mcp-gitlab

Windsurf & IntelliJ

Windsurf: Add to ~/.codeium/windsurf/mcp_config.json IntelliJ: Add to Settings | Tools | MCP Servers

Note: The actual server config starts at gitlab inside the mcpServers object.

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

Gemini CLI

gemini mcp add -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx gitlab uvx mcp-gitlab

pip / uv

uv pip install mcp-gitlab

</details>

Configuration

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:

Compatibility

Tools (83)

<details> <summary>Full tool reference (click to expand)</summary>

Projects

Project Approvals

Groups

Branches

Commits

Merge Requests

MR Notes

MR Discussions

Pipelines

Jobs

Tags

Releases

CI/CD Variables

Issues

</details>

Resources (7)

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

Prompts (6)

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

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

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.

Related MCP Servers

• mcp-atlassian-extended — Jira + Confluence integration (23 tools, 15 resources, 5 prompts)
• mcp-coda — Coda.io integration (54 tools, 12 resources, 5 prompts)

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