io.github.vish288/mcp-gitlab

Official

by vish288 · Python

MCP server for GitLab API — projects, MRs, pipelines, CI/CD, approvals, issues, code review.

Manage GitLab projects, merge requests, CI/CD pipelines, and code reviews via MCP.

Topics

ai-agentsci-cdcode-reviewdevopsgitlabgitlab-apigitlab-cimcpmcp-servermerge-requestsmodel-context-protocolpipelinespythoncursorvscodeself-hosted-gitlabfastmcpwindsurfgemini-cli-extensionai

README.md17 KBView on GitHub

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.

<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

bash

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.

json

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

Gemini CLI

bash

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

pip / uv

bash

uv pip install mcp-gitlab

</details>

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:

GITLAB_TOKEN
GITLAB_PAT
GITLAB_PERSONAL_ACCESS_TOKEN
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 (83)

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	16	list, get, create, update, merge, merge-sequence, rebase, changes, approve, unapprove, get approvals, list reviewers, list pipelines, list commits, subscribe, unsubscribe
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

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

Projects

Tool	Description
`gitlab_get_project`	Get project details
`gitlab_create_project`	Create a new project
`gitlab_delete_project`	Delete a project
`gitlab_update_project_merge_settings`	Update merge settings

Project Approvals

Tool	Description
`gitlab_get_project_approvals`	Get approval config
`gitlab_update_project_approvals`	Update approval settings
`gitlab_list_project_approval_rules`	List approval rules
`gitlab_create_project_approval_rule`	Create approval rule
`gitlab_update_project_approval_rule`	Update approval rule
`gitlab_delete_project_approval_rule`	Delete approval rule
`gitlab_list_mr_approval_rules`	List MR approval rules
`gitlab_create_mr_approval_rule`	Create MR approval rule
`gitlab_update_mr_approval_rule`	Update MR approval rule
`gitlab_delete_mr_approval_rule`	Delete MR approval rule

Groups

Tool	Description
`gitlab_list_groups`	List groups
`gitlab_get_group`	Get group details
`gitlab_share_project_with_group`	Share project with group
`gitlab_unshare_project_with_group`	Unshare project from group
`gitlab_share_group_with_group`	Share group with group
`gitlab_unshare_group_with_group`	Unshare group from group

Branches

Tool	Description
`gitlab_list_branches`	List branches
`gitlab_create_branch`	Create a branch
`gitlab_delete_branch`	Delete a branch

Commits

Tool	Description
`gitlab_list_commits`	List commits
`gitlab_get_commit`	Get commit (with optional diff)
`gitlab_create_commit`	Create commit with file actions
`gitlab_compare`	Compare branches/tags/commits

Merge Requests

Tool	Description
`gitlab_list_mrs`	List merge requests
`gitlab_get_mr`	Get MR details
`gitlab_create_mr`	Create merge request
`gitlab_update_mr`	Update merge request
`gitlab_merge_mr`	Merge a merge request
`gitlab_merge_mr_sequence`	Merge multiple MRs in order
`gitlab_rebase_mr`	Rebase a merge request
`gitlab_mr_changes`	Get MR file changes
`gitlab_approve_mr`	Approve a merge request
`gitlab_unapprove_mr`	Remove approval from a merge request
`gitlab_get_mr_approvals`	Get MR approval state
`gitlab_list_mr_pipelines`	List MR pipelines
`gitlab_list_mr_commits`	List MR commits
`gitlab_subscribe_mr`	Subscribe to MR notifications
`gitlab_unsubscribe_mr`	Unsubscribe from MR notifications

MR Notes

Tool	Description
`gitlab_list_mr_notes`	List MR comments
`gitlab_add_mr_note`	Add comment to MR
`gitlab_delete_mr_note`	Delete MR comment
`gitlab_update_mr_note`	Update MR comment
`gitlab_award_emoji`	Award emoji to note
`gitlab_remove_emoji`	Remove emoji from note

MR Discussions

Tool	Description
`gitlab_list_mr_discussions`	List discussions
`gitlab_create_mr_discussion`	Create discussion (inline + multi-line)
`gitlab_reply_to_discussion`	Reply to discussion
`gitlab_resolve_discussion`	Resolve/unresolve discussion

Pipelines

Tool	Description
`gitlab_list_pipelines`	List pipelines
`gitlab_get_pipeline`	Get pipeline (with optional jobs)
`gitlab_create_pipeline`	Trigger pipeline
`gitlab_retry_pipeline`	Retry failed jobs
`gitlab_cancel_pipeline`	Cancel pipeline

Jobs

Tool	Description
`gitlab_retry_job`	Retry a job
`gitlab_play_job`	Trigger manual job
`gitlab_cancel_job`	Cancel a job
`gitlab_get_job_log`	Get job log output

Tool	Description
`gitlab_list_tags`	List tags
`gitlab_get_tag`	Get tag details
`gitlab_create_tag`	Create a tag
`gitlab_delete_tag`	Delete a tag

Releases

Tool	Description
`gitlab_list_releases`	List releases
`gitlab_get_release`	Get release details
`gitlab_create_release`	Create a release
`gitlab_update_release`	Update a release
`gitlab_delete_release`	Delete a release

CI/CD Variables

Tool	Description
`gitlab_list_variables`	List project variables
`gitlab_create_variable`	Create project variable
`gitlab_update_variable`	Update project variable
`gitlab_delete_variable`	Delete project variable
`gitlab_list_group_variables`	List group variables
`gitlab_create_group_variable`	Create group variable
`gitlab_update_group_variable`	Update group variable
`gitlab_delete_group_variable`	Delete group variable

Issues

Tool	Description
`gitlab_list_issues`	List issues
`gitlab_get_issue`	Get issue details
`gitlab_create_issue`	Create an issue
`gitlab_update_issue`	Update an issue
`gitlab_add_issue_comment`	Add comment to issue

</details>

Resources (7)

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
`resource://guides/approval-workflow`	Approval Workflow Guide	Approval types, project vs MR-level rules, SHA safety, merge readiness

Prompts (6)

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
`approve_mr`	`project_id`, `mr_iid`	Check approvals → verify pipeline → review changes → approve or request changes
`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

code

"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

code

"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

code

"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

code

"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

bash

# 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.

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

Development

bash

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

Install

Configuration

Environment variables

GITLAB_TOKENrequiredsecret

GitLab personal access token (also accepts GITLAB_PAT or GITLAB_API_TOKEN)

GITLAB_URLrequired

GitLab instance URL (e.g. https://gitlab.com)

GITLAB_READ_ONLY

Restrict to read-only operations (true/false)

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-gitlab": {
      "command": "uvx",
      "args": [
        "mcp-gitlab"
      ],
      "env": {
        "GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>",
        "GITLAB_URL": "<YOUR_GITLAB_URL>",
        "GITLAB_READ_ONLY": "<YOUR_GITLAB_READ_ONLY>"
      }
    }
  }
}

Topics

mcp-gitlab

1-Click Installation

Claude Code

Windsurf & IntelliJ

Gemini CLI

pip / uv

Configuration

Supported Token Types

Compatibility

Tools (83)

Projects

Project Approvals

Groups

Branches

Commits

Merge Requests

MR Notes

MR Discussions

Pipelines

Jobs

Tags

Releases

CI/CD Variables

Issues

Resources (7)

Prompts (6)

Usage Examples

Projects & Branches

Merge Requests & Code Review

Pipelines & CI/CD

Issues

Security Considerations

Rate Limits & Permissions

Rate Limits

Required Permissions

CLI & Transport Options

Related MCP Servers

Development

License

Install

Configuration