gitlab mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| GITLAB_API_URL | No | Your GitLab API URL. Defaults to https://gitlab.com/api/v4 | https://gitlab.com/api/v4 |
| GITLAB_PERSONAL_ACCESS_TOKEN | Yes | Your GitLab personal access token. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
GitLab MCP. Default list: 38 core tools plus discover_tools and help (40). Call help for workflows. MR review: list_merge_request_changed_files, then get_merge_request_file_diff for 3-5 files. Do not dump get_merge_request_diffs. project_id: numeric ID or URL-encoded path (group%2Fproject). MR !123 uses merge_request_iid=123. discover_tools: omit category to list; pass a category to activate for this session. Prefer this over GITLAB_TOOLSETS=all. Session-only; with OAUTH_STATELESS_MODE=true persist GITLAB_TOOLSETS=core,. api is explicit-only (GITLAB_TOOLSETS=api). Shrink results: pass jmespath on any tool. Set GITLAB_MCP_COMPACT_RESULTS for oversized replies. Paginate get_pipeline_job_output. Prefer typed tools over execute_graphql. Do not enable gitlab_api_request unless you accept allowlist and safety-check bypass. Prompt injection can drive it. Destructive tools change GitLab state. Use the CLI (zereight-mcp-gitlab) for full diffs, logs, and artifacts.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": true
} |
| resources | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| get_merge_request_approval_stateA | Get merge request approval details including approvers. Inspect approval rules and approvers before merging. Use |
| search_repositoriesA | Search for GitLab projects. If the identifier is known, use a typed get or list tool. |
| get_file_contentsC | Get contents of a file or directory from a GitLab project. |
| create_issueB | Create a new issue. Open a new issue. Use |
| create_merge_requestA | Create a new merge request. Open a merge request from an existing source branch to a target. Use |
| get_branchA | Get branch details (commit, protection status). To find resources, use the matching list or search tool. |
| list_branchesB | List branches in project with search filter. For one known resource, use the matching get tool. |
| get_merge_requestA | Get details of a merge request (merge_request_iid or source_branch required). Set include_summaries=true for deployment/commit/approval summaries. To find resources, use the matching list or search tool. |
| get_merge_request_diffsB | Get the changes/diffs of a merge request (merge_request_iid or source_branch required). To find resources, use the matching list or search tool. |
| list_merge_request_changed_filesA | List changed file paths in a merge request without diff content (merge_request_iid or source_branch required). |
| list_merge_request_diffsA | List merge request diffs with pagination (merge_request_iid or source_branch required). For one known resource, use the matching get tool. |
| get_merge_request_file_diffA | Get diffs for specific files from a merge request (merge_request_iid or source_branch required). |
| update_merge_requestA | Update a merge request (merge_request_iid or source_branch required). Use the create tool for new resources and a note tool for comments. |
| create_merge_request_threadA | Create a new thread on a merge request. Start a review thread. Use |
| resolve_merge_request_threadA | Resolve a thread on a merge request. Mark an existing review thread resolved. Use |
| mr_discussionsA | List discussion items for a merge request. List complete discussion threads. Use |
| get_merge_request_discussionA | Get a single discussion item for a merge request. Fetch one discussion by id. Use |
| get_merge_request_noteA | Get a specific note for a merge request. Fetch one note by id. Use |
| get_merge_request_notesA | List notes for a merge request. List flat notes. Use |
| create_issue_noteA | Add a note to an issue, optionally replying to a discussion thread. Add a note to an existing issue, optionally as a reply. Use |
| list_issuesA | List issues (default: created by current user; use scope='all' for all). Use this for issue management. Optional |
| my_issuesA | List issues assigned to the authenticated user. Use this for issue management. Use |
| get_issueA | Get one issue. Slim nested milestone by default; full_response=true for the complete milestone. Use this for issue management. Use |
| update_issueA | Update an issue. Slim confirmation by default; full_response=true for the complete object. Change fields on an existing issue. Use |
| update_issue_description_patchA | Patch an issue description (search/replace or unified diff) without resending the full body. dry_run previews; create_note summarizes. |
| list_issue_discussionsB | List discussions for an issue. List threaded discussions for an issue. Use |
| get_projectB | Get details of a specific project. To find resources, use the matching list or search tool. |
| list_projectsA | List projects accessible by the current user. For one known resource, use the matching get tool. |
| list_project_membersA | List members of a GitLab project. Search project members by name or username. Use |
| list_labelsB | List labels for a project. For one known resource, use the matching get tool. |
| get_repository_treeC | List files and directories in a repository. |
| list_merge_requestsA | List merge requests (without project_id: user's MRs; with project_id: project MRs). For one known resource, use the matching get tool. |
| whoamiA | Get current authenticated user details. Requires classic read_user or fine-grained User:Read. Use |
| list_commitsB | List repository commits with filtering options. For one known resource, use the matching get tool. |
| get_commitB | Get details of a specific commit. To find resources, use the matching list or search tool. |
| get_commit_diffA | Get changes/diffs of a specific commit. Return the file diffs for one commit. Use |
| get_file_blameA | Get git blame for a file at a given ref. Each entry maps a contiguous range of source lines to the commit that last changed them (id, author, authored_date, message). Use range_start/range_end to limit blame to specific lines. |
| health_checkA | Check auth and versions. Always includes mcp_server_version. When authenticated, also GitLab version, revision, and enterprise from GET /api/v4/version. Version lookup failures omit those fields instead of failing. |
| discover_toolsA | List or activate a toolset for this session. Omit category to list; pass one to enable. Prefer this over GITLAB_TOOLSETS=all (loads ~all schemas). Session-only; with OAUTH_STATELESS_MODE=true persist |
| helpA | Return a short GitLab workflow guide. Omit topic for the overview and topic list. Topics: code-review, merge-requests, issues, pipelines, search, token-saving. Prefer discover_tools over GITLAB_TOOLSETS=all. With OAUTH_STATELESS_MODE=true persist GITLAB_TOOLSETS instead. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| review_merge_request | Review a merge request's diff in batches and leave threaded comments. |
| triage_pipeline_failure | Find the failing job in a pipeline and pull its log tail for diagnosis. |
| triage_vulnerabilities | List a project's open vulnerabilities and propose a remediation priority order. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| auth-setup | Local token auth and browser OAuth. |
| toolsets | How the enabled toolset list is chosen. |
| permission-modes | How permission mode limits tool calls. |
TDQS
Scored across 40 tools
Most tools target distinct resources, but the merge request surface has several closely related note, discussion, and diff tools (e.g., get_merge_request_discussion vs get_merge_request_note vs mr_discussions, and list_merge_request_diffs vs get_merge_request_diffs vs get_merge_request_file_diff). Descriptions provide 'use X instead' guidance, but an agent still has meaningful risk of selecting the wrong granularity.
The majority of tools follow a predictable verb_noun snake_case pattern (list_issues, get_merge_request, create_issue). There are notable deviations like mr_discussions, my_issues, whoami, help, and health_check, but these are limited and still readable.
At 40 tools, the surface is heavy for a single MCP server and includes very granular merge request diff/note variants. While GitLab is a broad domain, the presence of discover_tools implies these should be split into toolsets rather than loaded all at once.
Core GitLab workflows are only partially covered: branch creation/deletion, MR merge/approve, label management, and user lookup tools are missing, even though related tools reference them (e.g., get_user, approve_merge_request, update_merge_request_discussion_note). Agents will hit dead ends for common write operations.