{"id":45652275,"url":"https://github.com/vish288/mcp-gitlab","last_synced_at":"2026-03-03T02:07:44.672Z","repository":{"id":339849457,"uuid":"1163585440","full_name":"vish288/mcp-gitlab","owner":"vish288","description":"MCP server for GitLab API with 65+ tools: projects, merge requests, pipelines, CI/CD, approvals, issues, branches, tags, releases, variables, discussions. Works with Claude, Cursor, VS Code, Windsurf. Python, pip-installable.","archived":false,"fork":false,"pushed_at":"2026-02-24T06:40:00.000Z","size":432,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-24T10:53:30.527Z","etag":null,"topics":["ai","ai-agents","api-integration","automation","ci-cd","claude","code-review","cursor","devops","gitlab","gitlab-api","gitlab-ci","llm","mcp","mcp-server","mcp-tools","merge-requests","model-context-protocol","pipelines","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vish288.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-21T21:09:35.000Z","updated_at":"2026-02-24T06:40:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vish288/mcp-gitlab","commit_stats":null,"previous_names":["vish288/mcp-gitlab"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/vish288/mcp-gitlab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vish288%2Fmcp-gitlab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vish288%2Fmcp-gitlab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vish288%2Fmcp-gitlab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vish288%2Fmcp-gitlab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vish288","download_url":"https://codeload.github.com/vish288/mcp-gitlab/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vish288%2Fmcp-gitlab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29885808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T23:51:21.483Z","status":"online","status_checked_at":"2026-02-27T02:00:06.759Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","api-integration","automation","ci-cd","claude","code-review","cursor","devops","gitlab","gitlab-api","gitlab-ci","llm","mcp","mcp-server","mcp-tools","merge-requests","model-context-protocol","pipelines","python"],"created_at":"2026-02-24T06:49:12.888Z","updated_at":"2026-02-27T05:19:34.822Z","avatar_url":"https://github.com/vish288.png","language":"Python","readme":"# mcp-gitlab\n\n[![PyPI version](https://img.shields.io/pypi/v/mcp-gitlab)](https://pypi.org/project/mcp-gitlab/)\n[![PyPI downloads](https://img.shields.io/pypi/dm/mcp-gitlab)](https://pypi.org/project/mcp-gitlab/)\n[![Python](https://img.shields.io/pypi/pyversions/mcp-gitlab)](https://pypi.org/project/mcp-gitlab/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![CI](https://github.com/vish288/mcp-gitlab/actions/workflows/tests.yml/badge.svg)](https://github.com/vish288/mcp-gitlab/actions/workflows/tests.yml)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/servers/io.github.vish288/mcp-gitlab)\n\n\u003c!-- mcp-name: io.github.vish288/mcp-gitlab --\u003e\n\n**mcp-gitlab** is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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.\n\nBuilt with [FastMCP](https://github.com/jlowin/fastmcp), [httpx](https://www.python-httpx.org/), and [Pydantic](https://docs.pydantic.dev/).\n\n## 1-Click Installation\n\n[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://vish288.github.io/mcp-install?server=mcp-gitlab\u0026install=cursor)\n\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square\u0026logo=visualstudiocode\u0026logoColor=white)](https://vish288.github.io/mcp-install?server=mcp-gitlab\u0026install=vscode) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square\u0026logo=visualstudiocode\u0026logoColor=white)](https://vish288.github.io/mcp-install?server=mcp-gitlab\u0026install=vscode-insiders)\n\n\u003e **💡 Tip:** For other AI assistants (Claude Code, Windsurf, IntelliJ), visit the **[GitLab MCP Installation Gateway](https://vish288.github.io/mcp-install?server=mcp-gitlab)**.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eManual Setup Guides (Click to expand)\u003c/b\u003e\u003c/summary\u003e\n\u003cbr/\u003e\n\n\u003e Prerequisite: Install `uv` first (required for all `uvx` install flows). [Install uv](https://docs.astral.sh/uv/getting-started/installation/).\n\n### Claude Code\n\n```bash\nclaude mcp add gitlab -- uvx mcp-gitlab\n```\n\n### Windsurf \u0026 IntelliJ\n\n**Windsurf:** Add to `~/.codeium/windsurf/mcp_config.json`\n**IntelliJ:** Add to `Settings | Tools | MCP Servers`\n\n\u003e **Note:** The actual server config starts at `gitlab` inside the `mcpServers` object.\n\n```json\n{\n  \"mcpServers\": {\n    \"gitlab\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-gitlab\"],\n      \"env\": {\n        \"GITLAB_URL\": \"https://gitlab.example.com\",\n        \"GITLAB_TOKEN\": \"glpat-xxxxxxxxxxxxxxxxxxxx\"\n      }\n    }\n  }\n}\n```\n\n### pip / uv\n\n```bash\nuv pip install mcp-gitlab\n```\n\n\u003c/details\u003e\n\n## Configuration\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `GITLAB_URL` | **Yes** | - | GitLab instance URL (e.g. `https://gitlab.example.com`) |\n| `GITLAB_TOKEN` | **Yes** | - | Authentication token (see below) |\n| `GITLAB_READ_ONLY` | No | `false` | Set to `true` to disable write operations |\n| `GITLAB_TIMEOUT` | No | `30` | Request timeout in seconds |\n| `GITLAB_SSL_VERIFY` | No | `true` | Set to `false` to skip SSL verification |\n\n### Supported Token Types\n\nThe server checks these environment variables in order — first match wins:\n\n1. `GITLAB_TOKEN`\n2. `GITLAB_PAT`\n3. `GITLAB_PERSONAL_ACCESS_TOKEN`\n4. `GITLAB_API_TOKEN`\n\nThese accept any of the following token types:\n\n| Token Type | Format | Use Case |\n|------------|--------|----------|\n| Personal access token | `glpat-xxx` | User-level access with `api` scope |\n| OAuth2 token | `oauth-xxx` | OAuth app integrations |\n| CI job token | `$CI_JOB_TOKEN` | GitLab CI pipeline access |\n\n## Compatibility\n\n| Client | Supported | Install Method |\n|--------|-----------|----------------|\n| Claude Desktop | Yes | `claude_desktop_config.json` |\n| Claude Code | Yes | `claude mcp add` |\n| Cursor | Yes | One-click deeplink or `.cursor/mcp.json` |\n| VS Code Copilot | Yes | One-click deeplink or `.vscode/mcp.json` |\n| Windsurf | Yes | `~/.codeium/windsurf/mcp_config.json` |\n| Any MCP client | Yes | stdio or HTTP transport |\n\n## Tools (76)\n\n| Category | Count | Tools |\n|----------|-------|-------|\n| **Projects** | 4 | get, create, delete, update merge settings |\n| **Project Approvals** | 10 | get/update config, CRUD approval rules (project + MR) |\n| **Groups** | 6 | list, get, share/unshare project, share/unshare group |\n| **Branches** | 3 | list, create, delete |\n| **Commits** | 4 | list, get (with diff), create, compare |\n| **Merge Requests** | 8 | list, get, create, update, merge, merge-sequence, rebase, changes |\n| **MR Notes** | 6 | list, add, delete, update, award emoji, remove emoji |\n| **MR Discussions** | 4 | list, create (inline + multi-line), reply, resolve |\n| **Pipelines** | 5 | list, get (with jobs), create, retry, cancel |\n| **Jobs** | 4 | retry, play, cancel, get log |\n| **Tags** | 4 | list, get, create, delete |\n| **Releases** | 5 | list, get, create, update, delete |\n| **CI/CD Variables** | 8 | CRUD for project variables, CRUD for group variables |\n| **Issues** | 5 | list, get, create, update, add comment |\n\n\u003cdetails\u003e\n\u003csummary\u003eFull tool reference (click to expand)\u003c/summary\u003e\n\n### Projects\n| Tool | Description |\n|------|-------------|\n| `gitlab_get_project` | Get project details |\n| `gitlab_create_project` | Create a new project |\n| `gitlab_delete_project` | Delete a project |\n| `gitlab_update_project_merge_settings` | Update merge settings |\n\n### Project Approvals\n| Tool | Description |\n|------|-------------|\n| `gitlab_get_project_approvals` | Get approval config |\n| `gitlab_update_project_approvals` | Update approval settings |\n| `gitlab_list_project_approval_rules` | List approval rules |\n| `gitlab_create_project_approval_rule` | Create approval rule |\n| `gitlab_update_project_approval_rule` | Update approval rule |\n| `gitlab_delete_project_approval_rule` | Delete approval rule |\n| `gitlab_list_mr_approval_rules` | List MR approval rules |\n| `gitlab_create_mr_approval_rule` | Create MR approval rule |\n| `gitlab_update_mr_approval_rule` | Update MR approval rule |\n| `gitlab_delete_mr_approval_rule` | Delete MR approval rule |\n\n### Groups\n| Tool | Description |\n|------|-------------|\n| `gitlab_list_groups` | List groups |\n| `gitlab_get_group` | Get group details |\n| `gitlab_share_project_with_group` | Share project with group |\n| `gitlab_unshare_project_with_group` | Unshare project from group |\n| `gitlab_share_group_with_group` | Share group with group |\n| `gitlab_unshare_group_with_group` | Unshare group from group |\n\n### Branches\n| Tool | Description |\n|------|-------------|\n| `gitlab_list_branches` | List branches |\n| `gitlab_create_branch` | Create a branch |\n| `gitlab_delete_branch` | Delete a branch |\n\n### Commits\n| Tool | Description |\n|------|-------------|\n| `gitlab_list_commits` | List commits |\n| `gitlab_get_commit` | Get commit (with optional diff) |\n| `gitlab_create_commit` | Create commit with file actions |\n| `gitlab_compare` | Compare branches/tags/commits |\n\n### Merge Requests\n| Tool | Description |\n|------|-------------|\n| `gitlab_list_mrs` | List merge requests |\n| `gitlab_get_mr` | Get MR details |\n| `gitlab_create_mr` | Create merge request |\n| `gitlab_update_mr` | Update merge request |\n| `gitlab_merge_mr` | Merge a merge request |\n| `gitlab_merge_mr_sequence` | Merge multiple MRs in order |\n| `gitlab_rebase_mr` | Rebase a merge request |\n| `gitlab_mr_changes` | Get MR file changes |\n\n### MR Notes\n| Tool | Description |\n|------|-------------|\n| `gitlab_list_mr_notes` | List MR comments |\n| `gitlab_add_mr_note` | Add comment to MR |\n| `gitlab_delete_mr_note` | Delete MR comment |\n| `gitlab_update_mr_note` | Update MR comment |\n| `gitlab_award_emoji` | Award emoji to note |\n| `gitlab_remove_emoji` | Remove emoji from note |\n\n### MR Discussions\n| Tool | Description |\n|------|-------------|\n| `gitlab_list_mr_discussions` | List discussions |\n| `gitlab_create_mr_discussion` | Create discussion (inline + multi-line) |\n| `gitlab_reply_to_discussion` | Reply to discussion |\n| `gitlab_resolve_discussion` | Resolve/unresolve discussion |\n\n### Pipelines\n| Tool | Description |\n|------|-------------|\n| `gitlab_list_pipelines` | List pipelines |\n| `gitlab_get_pipeline` | Get pipeline (with optional jobs) |\n| `gitlab_create_pipeline` | Trigger pipeline |\n| `gitlab_retry_pipeline` | Retry failed jobs |\n| `gitlab_cancel_pipeline` | Cancel pipeline |\n\n### Jobs\n| Tool | Description |\n|------|-------------|\n| `gitlab_retry_job` | Retry a job |\n| `gitlab_play_job` | Trigger manual job |\n| `gitlab_cancel_job` | Cancel a job |\n| `gitlab_get_job_log` | Get job log output |\n\n### Tags\n| Tool | Description |\n|------|-------------|\n| `gitlab_list_tags` | List tags |\n| `gitlab_get_tag` | Get tag details |\n| `gitlab_create_tag` | Create a tag |\n| `gitlab_delete_tag` | Delete a tag |\n\n### Releases\n| Tool | Description |\n|------|-------------|\n| `gitlab_list_releases` | List releases |\n| `gitlab_get_release` | Get release details |\n| `gitlab_create_release` | Create a release |\n| `gitlab_update_release` | Update a release |\n| `gitlab_delete_release` | Delete a release |\n\n### CI/CD Variables\n| Tool | Description |\n|------|-------------|\n| `gitlab_list_variables` | List project variables |\n| `gitlab_create_variable` | Create project variable |\n| `gitlab_update_variable` | Update project variable |\n| `gitlab_delete_variable` | Delete project variable |\n| `gitlab_list_group_variables` | List group variables |\n| `gitlab_create_group_variable` | Create group variable |\n| `gitlab_update_group_variable` | Update group variable |\n| `gitlab_delete_group_variable` | Delete group variable |\n\n### Issues\n| Tool | Description |\n|------|-------------|\n| `gitlab_list_issues` | List issues |\n| `gitlab_get_issue` | Get issue details |\n| `gitlab_create_issue` | Create an issue |\n| `gitlab_update_issue` | Update an issue |\n| `gitlab_add_issue_comment` | Add comment to issue |\n\n\u003c/details\u003e\n\n## Resources (6)\n\nThe server exposes curated workflow guides as [MCP resources](https://modelcontextprotocol.io/docs/concepts/resources) that clients can read on demand.\n\n| URI | Name | Description |\n|-----|------|-------------|\n| `resource://rules/gitlab-ci` | GitLab CI/CD Pipeline Patterns | Stage design, job rules, caching, artifacts, `needs` DAG, multi-project pipelines |\n| `resource://rules/git-workflow` | Git Workflow Standards | Branch naming, trunk-based flow, merge vs rebase, protected branches |\n| `resource://rules/mr-hygiene` | Merge Request Best Practices | MR size, description templates, review checklists, thread resolution |\n| `resource://rules/conventional-commits` | Conventional Commits Spec | Commit types, scopes, breaking changes, changelog generation |\n| `resource://guides/code-review` | Code Review Standards | Review priorities, inline comments, approval workflows, nit vs blocker |\n| `resource://guides/codeowners` | GitLab CODEOWNERS Reference | Syntax, section owners, approval rules, pattern matching |\n\n## Prompts (5)\n\nThe server provides [MCP prompts](https://modelcontextprotocol.io/docs/concepts/prompts) — reusable multi-tool workflow templates that clients can surface as slash commands.\n\n| Prompt | Parameters | Workflow |\n|--------|-----------|----------|\n| `review_mr` | `project_id`, `mr_iid` | Fetch MR → check pipeline → review changes → write discussion notes |\n| `diagnose_pipeline` | `project_id`, `pipeline_id` | Fetch pipeline → identify failed jobs → get logs → suggest fix |\n| `prepare_release` | `project_id`, `tag_name`, `ref` | Compare commits since last tag → draft changelog → create tag + release |\n| `setup_branch_protection` | `project_id` | Review settings → configure merge method → set approval rules |\n| `triage_issues` | `project_id`, `label` | List open issues → categorize → prioritize → identify duplicates |\n\n## Usage Examples\n\n### Projects \u0026 Branches\n\n```\n\"Get details for project my-org/api-gateway\"\n→ gitlab_get_project(project_id=\"my-org/api-gateway\")\n\n\"Create a feature branch from main\"\n→ gitlab_create_branch(project_id=\"123\", branch_name=\"feat/login\", ref=\"main\")\n\n\"Delete all branches merged into main\"\n→ gitlab_list_branches(project_id=\"123\") → filter merged → gitlab_delete_branch for each\n```\n\n### Merge Requests \u0026 Code Review\n\n```\n\"Open a merge request from feat/login to main\"\n→ gitlab_create_mr(project_id=\"123\", source_branch=\"feat/login\", target_branch=\"main\", title=\"Add login\")\n\n\"Review MR !42 — list changes and add inline comments\"\n→ gitlab_mr_changes(project_id=\"123\", mr_iid=42)\n→ gitlab_create_mr_discussion(project_id=\"123\", mr_iid=42, body=\"nit: ...\", new_path=\"src/auth.py\", new_line=15)\n\n\"Merge MR !42 after resolving all threads\"\n→ gitlab_list_mr_discussions(project_id=\"123\", mr_iid=42) → resolve unresolved\n→ gitlab_merge_mr(project_id=\"123\", mr_iid=42, squash=True)\n```\n\n### Pipelines \u0026 CI/CD\n\n```\n\"Show failed pipelines on main this week\"\n→ gitlab_list_pipelines(project_id=\"123\", ref=\"main\", status=\"failed\")\n\n\"Retry a failed pipeline\"\n→ gitlab_retry_pipeline(project_id=\"123\", pipeline_id=456)\n\n\"Get the build log for job 789\"\n→ gitlab_get_job_log(project_id=\"123\", job_id=789, tail_lines=100)\n```\n\n### Issues\n\n```\n\"Create a bug report in project 123\"\n→ gitlab_create_issue(project_id=\"123\", title=\"Login page 500 error\", labels=[\"bug\",\"P1\"])\n\n\"Find open issues assigned to me\"\n→ gitlab_list_issues(project_id=\"123\", state=\"opened\", assignee_username=\"johndoe\")\n```\n\n## Security Considerations\n\n- **Token scope**: Use the minimum required scope. `api` scope grants full access; prefer `read_api` for read-only deployments.\n- **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.\n- **SSL verification**: `GITLAB_SSL_VERIFY=true` by default. Only disable for self-signed certificates in trusted networks.\n- **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.\n- **MCP tool annotations**: Each tool declares `readOnlyHint`, `destructiveHint`, and `idempotentHint` for client-side permission prompts.\n- **No credential storage**: The server does not persist tokens. Credentials are read from environment variables at startup.\n\n## Rate Limits \u0026 Permissions\n\n### Rate Limits\n\nGitLab 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.\n\n### Required Permissions\n\n| Operation | Minimum GitLab Role |\n|-----------|-------------------|\n| Read projects, MRs, pipelines, issues | Reporter |\n| Create branches, MRs, issues | Developer |\n| Merge MRs, manage CI/CD variables | Maintainer |\n| Delete projects, manage approval rules | Maintainer/Owner |\n| Share projects/groups | Owner (or Admin) |\n\n## CLI \u0026 Transport Options\n\n```bash\n# Default: stdio transport (for MCP clients)\nuvx mcp-gitlab\n\n# HTTP transport (SSE or streamable-http)\nuvx mcp-gitlab --transport sse --host 127.0.0.1 --port 8000\nuvx mcp-gitlab --transport streamable-http --port 9000\n\n# CLI overrides for config\nuvx mcp-gitlab --gitlab-url https://gitlab.example.com --gitlab-token glpat-xxx --read-only\n```\n\nThe server loads `.env` files from the working directory automatically via `python-dotenv`.\n\n## Development\n\n```bash\ngit clone https://github.com/vish288/mcp-gitlab.git\ncd mcp-gitlab\nuv sync --all-extras\n\nuv run pytest --cov\nuv run ruff check .\nuv run ruff format --check .\n```\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvish288%2Fmcp-gitlab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvish288%2Fmcp-gitlab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvish288%2Fmcp-gitlab/lists"}