Lets an AI client manage GitLab projects, merge requests, issues, pipelines, wikis and releases through the GitLab API.
Also known as zereight/gitlab-mcp, gitlab-mcp, @zereight/mcp-gitlab
- Stars
- 2,105
- Tools
- 200
- Downloads, 30 days
- —
- Latest version
- 2.3.28
- Last commit
- Nov 14, 2026
- License
- MIT
What is GitLab MCP?
GitLab lets an AI client manage GitLab projects, merge requests, issues, pipelines, wikis and releases through the GitLab API. It exposes 200 tools, such as merge_merge_request, approve_merge_request, unapprove_merge_request.
Summary generated from the project's README
About GitLab MCP server
Managing GitLab projects, merge requests, issues, and pipelines directly from an AI client is what this server enables for developers. It provides a structured way for agents to interact with GitLab via the API, allowing for tasks like reviewing code diffs, checking pipeline job outputs, and managing wikis or releases. The server is designed to be efficient by starting with a lean set of 40 core tools to save on token usage, while offering access to up to 288 total tools through a discovery mechanism.
Users can deploy this server locally using stdio for IDEs like Cursor or Claude Code, or via remote HTTP for hosted environments like Claude.ai. Authentication is flexible, supporting Personal Access Tokens, local OAuth, or MCP OAuth for web connectors. It is built to handle complex workflows, such as batching merge request file diffs or filtering large JSON responses using JMESPath to keep chat contexts manageable.
What you can do with it
- 1Reviewing merge request changesAn AI agent can identify which files changed in a merge request and then retrieve the specific code diffs for review.
- 2Debugging CI/CD pipelinesDevelopers can ask an AI to find and read the output of specific pipeline jobs to troubleshoot failures.
- 3Optimizing token consumptionUsers can prevent overwhelming the model by activating specific tool categories only when needed during a session.
Written from the project's README. Every use case is checked against a quote from it.
How to install GitLab MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall GitLab MCP in Claude Code
$ claude mcp add --env 'GITLAB_JOB_TOKEN=<YOUR_GITLAB_JOB_TOKEN>' --env 'GITLAB_PERSONAL_ACCESS_TOKEN=<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>' gitlab-mcp -- npx -y @zereight/mcp-gitlabInstall GitLab MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"gitlab-mcp": {
"command": "npx",
"args": [
"-y",
"@zereight/mcp-gitlab"
],
"env": {
"GITLAB_JOB_TOKEN": "<YOUR_GITLAB_JOB_TOKEN>",
"GITLAB_PERSONAL_ACCESS_TOKEN": "<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>"
}
}
}
}Install GitLab MCP in VS Code
.vscode/mcp.json
{
"servers": {
"gitlab-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@zereight/mcp-gitlab"
],
"env": {
"GITLAB_JOB_TOKEN": "<YOUR_GITLAB_JOB_TOKEN>",
"GITLAB_PERSONAL_ACCESS_TOKEN": "<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>"
}
}
}
}Install GitLab MCP in VS Code CLI
$ code --add-mcp '{"name":"gitlab-mcp","type":"stdio","command":"npx","args":["-y","@zereight/mcp-gitlab"],"env":{"GITLAB_JOB_TOKEN":"<YOUR_GITLAB_JOB_TOKEN>","GITLAB_PERSONAL_ACCESS_TOKEN":"<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>"}}'Install GitLab MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"gitlab-mcp": {
"command": "npx",
"args": [
"-y",
"@zereight/mcp-gitlab"
],
"env": {
"GITLAB_JOB_TOKEN": "<YOUR_GITLAB_JOB_TOKEN>",
"GITLAB_PERSONAL_ACCESS_TOKEN": "<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>"
}
}
}
}Install GitLab MCP in Codex
$ codex mcp add gitlab-mcp --env 'GITLAB_JOB_TOKEN=<YOUR_GITLAB_JOB_TOKEN>' --env 'GITLAB_JOB_TOKEN=<YOUR_GITLAB_JOB_TOKEN>' --env 'GITLAB_PERSONAL_ACCESS_TOKEN=<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>' --env 'GITLAB_PERSONAL_ACCESS_TOKEN=<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>' -- npx -y @zereight/mcp-gitlabInstall GitLab MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.gitlab-mcp] command = "npx" args = ["-y", "@zereight/mcp-gitlab"] [mcp_servers.gitlab-mcp.env] GITLAB_JOB_TOKEN = "<YOUR_GITLAB_JOB_TOKEN>" GITLAB_PERSONAL_ACCESS_TOKEN = "<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>"
Install GitLab MCP in Gemini CLI
$ gemini mcp add -s user -e 'GITLAB_JOB_TOKEN=<YOUR_GITLAB_JOB_TOKEN>' -e 'GITLAB_JOB_TOKEN=<YOUR_GITLAB_JOB_TOKEN>' -e 'GITLAB_PERSONAL_ACCESS_TOKEN=<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>' -e 'GITLAB_PERSONAL_ACCESS_TOKEN=<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>' gitlab-mcp npx -- -y @zereight/mcp-gitlabInstall GitLab MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"gitlab-mcp": {
"command": "npx",
"args": [
"-y",
"@zereight/mcp-gitlab"
],
"env": {
"GITLAB_JOB_TOKEN": "<YOUR_GITLAB_JOB_TOKEN>",
"GITLAB_PERSONAL_ACCESS_TOKEN": "<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>"
}
}
}
}Needs a key before it starts
Started on 16 Nov 2026 with no keys, it stopped and asked for one, so a client sees no tools until you set the variables above.
GitLab MCP tools 200
Detected from the READMEmerge_merge_requestapprove_merge_requestunapprove_merge_requestget_merge_request_approval_stateget_merge_request_conflictslist_merge_request_pipelinesexecute_graphqlcreate_or_update_filesearch_repositoriescreate_repositorycreate_groupget_file_contents
| merge_merge_request | — | |
| approve_merge_request | — | |
| unapprove_merge_request | — | |
| get_merge_request_approval_state | — | |
| get_merge_request_conflicts | — | |
| list_merge_request_pipelines | — | |
| execute_graphql | — | |
| create_or_update_file | — | |
| search_repositories | — | |
| create_repository | — | |
| create_group | — | |
| get_file_contents | — |
Show all 200 toolsShow fewer tools
push_filescreate_issuecreate_merge_requestfork_repositorycreate_branchget_branchlist_branchesdelete_branchlist_protected_branchesget_protected_branchprotect_branchupdate_protected_branchunprotect_branchupdate_default_branchget_merge_requestget_merge_request_diffslist_merge_request_changed_fileslist_merge_request_diffsget_merge_request_file_difflist_merge_request_versionsget_merge_request_versionget_branch_diffsupdate_merge_requestcreate_notecreate_merge_request_threadresolve_merge_request_threadmr_discussionsget_merge_request_discussiondelete_merge_request_discussion_noteupdate_merge_request_discussion_notecreate_merge_request_discussion_notecreate_merge_request_notedelete_merge_request_noteget_merge_request_noteget_merge_request_notesupdate_merge_request_noteget_draft_notelist_draft_notescreate_draft_noteupdate_draft_notedelete_draft_notepublish_draft_notebulk_publish_draft_noteslist_merge_request_emoji_reactionslist_merge_request_note_emoji_reactionscreate_merge_request_emoji_reactiondelete_merge_request_emoji_reactioncreate_merge_request_note_emoji_reactiondelete_merge_request_note_emoji_reactionupdate_issue_notecreate_issue_notelist_issue_emoji_reactionslist_issue_note_emoji_reactionscreate_issue_emoji_reactiondelete_issue_emoji_reactioncreate_issue_note_emoji_reactiondelete_issue_note_emoji_reactionlist_issuesmy_issuesget_issueupdate_issueupdate_issue_description_patchreorder_issuedelete_issuelist_todosmark_todo_donemark_all_todos_donelist_issue_linkslist_issue_discussionsget_issue_linkcreate_issue_linkdelete_issue_linklist_namespacesget_namespaceverify_namespaceget_projectlist_projectsupdate_projectlist_project_memberslist_group_memberslist_labelsget_labelcreate_labelupdate_labeldelete_labellist_group_projectslist_wiki_pagesget_wiki_pagecreate_wiki_pageupdate_wiki_pagedelete_wiki_pagelist_group_wiki_pagesget_group_wiki_pagecreate_group_wiki_pageupdate_group_wiki_pagedelete_group_wiki_pageget_repository_treelist_pipelinesget_pipelineget_pipeline_variablesget_pipeline_test_reportget_pipeline_test_report_summarydelete_pipelineupdate_pipeline_metadatalist_deploymentsget_deploymentcreate_deploymentupdate_deploymentdelete_deploymentlist_deployment_merge_requestsapprove_deploymentlist_environmentsget_environmentupdate_environmentdelete_environmentstop_environmentstop_stale_environmentsdelete_review_app_environmentslist_pipeline_triggersget_pipeline_triggercreate_pipeline_triggerupdate_pipeline_triggerdelete_pipeline_triggertrigger_pipelinelist_pipeline_jobslist_pipeline_trigger_jobsget_pipeline_jobget_pipeline_job_outputvalidate_ci_lintvalidate_project_ci_lintlist_ci_catalog_resourcesget_ci_catalog_resourcecreate_pipelineretry_pipelinecancel_pipelinelist_pipeline_schedulesget_pipeline_schedulelist_pipeline_schedule_pipelinescreate_pipeline_scheduleupdate_pipeline_scheduledelete_pipeline_scheduleplay_pipeline_scheduletake_ownership_pipeline_scheduleget_pipeline_schedule_variablecreate_pipeline_schedule_variableupdate_pipeline_schedule_variabledelete_pipeline_schedule_variableplay_pipeline_jobplay_pipeline_jobsretry_pipeline_jobcancel_pipeline_joberase_pipeline_jobwait_for_pipelinewait_for_joblist_job_artifactsdownload_job_artifactsget_job_artifact_filelist_merge_requestslist_group_merge_requestslist_milestonesget_milestonecreate_milestoneedit_milestonedelete_milestoneget_milestone_issueget_milestone_merge_requestspromote_milestoneget_milestone_burndown_eventslist_group_milestonesget_group_milestonecreate_group_milestoneedit_group_milestonedelete_group_milestoneget_group_milestone_issueget_group_milestone_merge_requestsget_group_milestone_burndown_eventsget_usersget_userwhoamilist_commitsget_commitget_commit_diffget_file_blamelist_commit_statusescreate_commit_statuslist_group_iterationsget_group_iterationupdate_group_iteration
| push_files | — | |
| create_issue | — | |
| create_merge_request | — | |
| fork_repository | — | |
| create_branch | — | |
| get_branch | — | |
| list_branches | — | |
| delete_branch | — | |
| list_protected_branches | — | |
| get_protected_branch | — | |
| protect_branch | — | |
| update_protected_branch | — | |
| unprotect_branch | — | |
| update_default_branch | — | |
| get_merge_request | — | |
| get_merge_request_diffs | — | |
| list_merge_request_changed_files | — | |
| list_merge_request_diffs | — | |
| get_merge_request_file_diff | — | |
| list_merge_request_versions | — | |
| get_merge_request_version | — | |
| get_branch_diffs | — | |
| update_merge_request | — | |
| create_note | — | |
| create_merge_request_thread | — | |
| resolve_merge_request_thread | — | |
| mr_discussions | — | |
| get_merge_request_discussion | — | |
| delete_merge_request_discussion_note | — | |
| update_merge_request_discussion_note | — | |
| create_merge_request_discussion_note | — | |
| create_merge_request_note | — | |
| delete_merge_request_note | — | |
| get_merge_request_note | — | |
| get_merge_request_notes | — | |
| update_merge_request_note | — | |
| get_draft_note | — | |
| list_draft_notes | — | |
| create_draft_note | — | |
| update_draft_note | — | |
| delete_draft_note | — | |
| publish_draft_note | — | |
| bulk_publish_draft_notes | — | |
| list_merge_request_emoji_reactions | — | |
| list_merge_request_note_emoji_reactions | — | |
| create_merge_request_emoji_reaction | — | |
| delete_merge_request_emoji_reaction | — | |
| create_merge_request_note_emoji_reaction | — | |
| delete_merge_request_note_emoji_reaction | — | |
| update_issue_note | — | |
| create_issue_note | — | |
| list_issue_emoji_reactions | — | |
| list_issue_note_emoji_reactions | — | |
| create_issue_emoji_reaction | — | |
| delete_issue_emoji_reaction | — | |
| create_issue_note_emoji_reaction | — | |
| delete_issue_note_emoji_reaction | — | |
| list_issues | — | |
| my_issues | — | |
| get_issue | — | |
| update_issue | — | |
| update_issue_description_patch | — | |
| reorder_issue | — | |
| delete_issue | — | |
| list_todos | — | |
| mark_todo_done | — | |
| mark_all_todos_done | — | |
| list_issue_links | — | |
| list_issue_discussions | — | |
| get_issue_link | — | |
| create_issue_link | — | |
| delete_issue_link | — | |
| list_namespaces | — | |
| get_namespace | — | |
| verify_namespace | — | |
| get_project | — | |
| list_projects | — | |
| update_project | — | |
| list_project_members | — | |
| list_group_members | — | |
| list_labels | — | |
| get_label | — | |
| create_label | — | |
| update_label | — | |
| delete_label | — | |
| list_group_projects | — | |
| list_wiki_pages | — | |
| get_wiki_page | — | |
| create_wiki_page | — | |
| update_wiki_page | — | |
| delete_wiki_page | — | |
| list_group_wiki_pages | — | |
| get_group_wiki_page | — | |
| create_group_wiki_page | — | |
| update_group_wiki_page | — | |
| delete_group_wiki_page | — | |
| get_repository_tree | — | |
| list_pipelines | — | |
| get_pipeline | — | |
| get_pipeline_variables | — | |
| get_pipeline_test_report | — | |
| get_pipeline_test_report_summary | — | |
| delete_pipeline | — | |
| update_pipeline_metadata | — | |
| list_deployments | — | |
| get_deployment | — | |
| create_deployment | — | |
| update_deployment | — | |
| delete_deployment | — | |
| list_deployment_merge_requests | — | |
| approve_deployment | — | |
| list_environments | — | |
| get_environment | — | |
| update_environment | — | |
| delete_environment | — | |
| stop_environment | — | |
| stop_stale_environments | — | |
| delete_review_app_environments | — | |
| list_pipeline_triggers | — | |
| get_pipeline_trigger | — | |
| create_pipeline_trigger | — | |
| update_pipeline_trigger | — | |
| delete_pipeline_trigger | — | |
| trigger_pipeline | — | |
| list_pipeline_jobs | — | |
| list_pipeline_trigger_jobs | — | |
| get_pipeline_job | — | |
| get_pipeline_job_output | — | |
| validate_ci_lint | — | |
| validate_project_ci_lint | — | |
| list_ci_catalog_resources | — | |
| get_ci_catalog_resource | — | |
| create_pipeline | — | |
| retry_pipeline | — | |
| cancel_pipeline | — | |
| list_pipeline_schedules | — | |
| get_pipeline_schedule | — | |
| list_pipeline_schedule_pipelines | — | |
| create_pipeline_schedule | — | |
| update_pipeline_schedule | — | |
| delete_pipeline_schedule | — | |
| play_pipeline_schedule | — | |
| take_ownership_pipeline_schedule | — | |
| get_pipeline_schedule_variable | — | |
| create_pipeline_schedule_variable | — | |
| update_pipeline_schedule_variable | — | |
| delete_pipeline_schedule_variable | — | |
| play_pipeline_job | — | |
| play_pipeline_jobs | — | |
| retry_pipeline_job | — | |
| cancel_pipeline_job | — | |
| erase_pipeline_job | — | |
| wait_for_pipeline | — | |
| wait_for_job | — | |
| list_job_artifacts | — | |
| download_job_artifacts | — | |
| get_job_artifact_file | — | |
| list_merge_requests | — | |
| list_group_merge_requests | — | |
| list_milestones | — | |
| get_milestone | — | |
| create_milestone | — | |
| edit_milestone | — | |
| delete_milestone | — | |
| get_milestone_issue | — | |
| get_milestone_merge_requests | — | |
| promote_milestone | — | |
| get_milestone_burndown_events | — | |
| list_group_milestones | — | |
| get_group_milestone | — | |
| create_group_milestone | — | |
| edit_group_milestone | — | |
| delete_group_milestone | — | |
| get_group_milestone_issue | — | |
| get_group_milestone_merge_requests | — | |
| get_group_milestone_burndown_events | — | |
| get_users | — | |
| get_user | — | |
| whoami | — | |
| list_commits | — | |
| get_commit | — | |
| get_commit_diff | — | |
| get_file_blame | — | |
| list_commit_statuses | — | |
| create_commit_status | — | |
| list_group_iterations | — | |
| get_group_iteration | — | |
| update_group_iteration | — |
Configuration
GITLAB_JOB_TOKENSecretOptional GitLab CI job token to use instead of a personal access token when running inside GitLab CI.
GITLAB_JOB_TOKENSecretOptional GitLab CI job token to use instead of a personal access token when running inside GitLab CI.
GITLAB_PERSONAL_ACCESS_TOKENSecretGitLab personal access token for local stdio use. A non-empty value overrides GITLAB_PERSONAL_ACCESS_TOKEN_FILE. One of this token, GITLAB_PERSONAL_ACCESS_TOKEN_FILE, GITLAB_JOB_TOKEN, GITLAB_AUTH_COOKIE_PATH, or GITLAB_USE_OAUTH=true must be set. Create a token with the GitLab scopes the tools need, such as api or read_api.
GITLAB_PERSONAL_ACCESS_TOKENSecretGitLab personal access token for local stdio use. A non-empty value overrides GITLAB_PERSONAL_ACCESS_TOKEN_FILE. One of this token, GITLAB_PERSONAL_ACCESS_TOKEN_FILE, GITLAB_JOB_TOKEN, GITLAB_AUTH_COOKIE_PATH, or GITLAB_USE_OAUTH=true must be set. Create a token with the GitLab scopes the tools need, such as api or read_api.
GITLAB_ALLOWED_PROJECT_IDSOptional comma-separated list of GitLab project IDs that this server is allowed to access.
GITLAB_ALLOWED_PROJECT_IDSOptional comma-separated list of GitLab project IDs that this server is allowed to access.
GITLAB_API_URLGITLAB_API_URLGitLab API base URL. Use https://gitlab.com/api/v4 for GitLab.com or your self-managed GitLab API URL.
GITLAB_API_URLGitLab API base URL. Use https://gitlab.com/api/v4 for GitLab.com or your self-managed GitLab API URL.
GITLAB_AUTH_COOKIE_PATHOptional path to a GitLab authentication cookie file for cookie-based authentication.
GITLAB_AUTH_COOKIE_PATHOptional path to a GitLab authentication cookie file for cookie-based authentication.
GITLAB_CA_CERT_PATHOptional path to a custom CA certificate file for self-managed GitLab instances.
GITLAB_CA_CERT_PATHOptional path to a custom CA certificate file for self-managed GitLab instances.
GITLAB_DENIED_TOOLS_REGEXOptional regular expression used to hide matching tools from the server.
GITLAB_DENIED_TOOLS_REGEXOptional regular expression used to hide matching tools from the server.
GITLAB_MASKING_CONFIGOptional path to a response-masking JSON configuration file.
GITLAB_MASKING_CONFIGOptional path to a response-masking JSON configuration file.
GITLAB_MASKING_ENABLEDSet to true to mask text tool results and returned errors using built-in or configured rules.
GITLAB_MASKING_ENABLEDSet to true to mask text tool results and returned errors using built-in or configured rules.
GITLAB_MASKING_POLICY_FILEOptional protected server-owned JSON file containing managed masking policies.
GITLAB_MASKING_POLICY_FILEOptional protected server-owned JSON file containing managed masking policies.
GITLAB_MASKING_WORKSPACE_DIRDirectory used to resolve response-masking configuration paths.
GITLAB_MASKING_WORKSPACE_DIRDirectory used to resolve response-masking configuration paths.
GITLAB_MCP_OAUTHGITLAB_OAUTH_APP_IDGITLAB_OAUTH_CLIENT_IDGitLab OAuth application ID. When GITLAB_USE_OAUTH=true, set this or GITLAB_OAUTH_TOKEN_SCRIPT.
GITLAB_OAUTH_CLIENT_IDGitLab OAuth application ID. When GITLAB_USE_OAUTH=true, set this or GITLAB_OAUTH_TOKEN_SCRIPT.
GITLAB_OAUTH_TOKEN_SCRIPTCommand that prints an OAuth access token. When GITLAB_USE_OAUTH=true, set this or GITLAB_OAUTH_CLIENT_ID.
GITLAB_OAUTH_TOKEN_SCRIPTCommand that prints an OAuth access token. When GITLAB_USE_OAUTH=true, set this or GITLAB_OAUTH_CLIENT_ID.
GITLAB_PERMISSION_MODETool exposure. Allowed values are readonly, modify, and full. Unset uses full. readonly keeps read-only tools. modify blocks delete and teardown tools.
GITLAB_PERMISSION_MODETool exposure. Allowed values are readonly, modify, and full. Unset uses full. readonly keeps read-only tools. modify blocks delete and teardown tools.
GITLAB_PERSONAL_ACCESS_TOKEN_FILEPath to a file that contains the personal access token. Read once at startup and trimmed. Ignored when GITLAB_PERSONAL_ACCESS_TOKEN or --token is non-empty. A missing, unreadable, or empty file stops startup. Does not replace job token, OAuth, cookie, or remote authorization.
GITLAB_PERSONAL_ACCESS_TOKEN_FILEPath to a file that contains the personal access token. Read once at startup and trimmed. Ignored when GITLAB_PERSONAL_ACCESS_TOKEN or --token is non-empty. A missing, unreadable, or empty file stops startup. Does not replace job token, OAuth, cookie, or remote authorization.
GITLAB_TOOLSOptional comma-separated list of individual tool names to add on top of enabled toolsets.
GITLAB_TOOLSOptional comma-separated list of individual tool names to add on top of enabled toolsets.
GITLAB_TOOLSETSOptional comma-separated toolset ids (projects, issues, merge_requests, …). Unset keeps the lean core default plus discover_tools. Do not set all unless you accept loading ~all schemas (~73k tokens).
GITLAB_TOOLSETSOptional comma-separated toolset ids (projects, issues, merge_requests, …). Unset keeps the lean core default plus discover_tools. Do not set all unless you accept loading ~all schemas (~73k tokens).
GITLAB_TOOL_POLICY_APPROVEOptional comma-separated list of tool names that require explicit approval before execution.
GITLAB_TOOL_POLICY_APPROVEOptional comma-separated list of tool names that require explicit approval before execution.
GITLAB_TOOL_POLICY_HIDDENOptional comma-separated list of tool names to hide from tools/list.
GITLAB_TOOL_POLICY_HIDDENOptional comma-separated list of tool names to hide from tools/list.
GITLAB_USE_OAUTHSet to true to start with GitLab OAuth instead of a personal access token, job token, or cookie file.
GITLAB_USE_OAUTHSet to true to start with GitLab OAuth instead of a personal access token, job token, or cookie file.
MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URLMCP_SERVER_URLNODE_TLS_REJECT_UNAUTHORIZEDSet to 0 only when you intentionally need to connect to a GitLab instance with invalid or self-signed TLS certificates.
NODE_TLS_REJECT_UNAUTHORIZEDSet to 0 only when you intentionally need to connect to a GitLab instance with invalid or self-signed TLS certificates.
STREAMABLE_HTTP
| Name | Description | |
|---|---|---|
| GITLAB_JOB_TOKEN | Optional GitLab CI job token to use instead of a personal access token when running inside GitLab CI. | Secret |
| GITLAB_JOB_TOKEN | Optional GitLab CI job token to use instead of a personal access token when running inside GitLab CI. | Secret |
| GITLAB_PERSONAL_ACCESS_TOKEN | GitLab personal access token for local stdio use. A non-empty value overrides GITLAB_PERSONAL_ACCESS_TOKEN_FILE. One of this token, GITLAB_PERSONAL_ACCESS_TOKEN_FILE, GITLAB_JOB_TOKEN, GITLAB_AUTH_COOKIE_PATH, or GITLAB_USE_OAUTH=true must be set. Create a token with the GitLab scopes the tools need, such as api or read_api. | Secret |
| GITLAB_PERSONAL_ACCESS_TOKEN | GitLab personal access token for local stdio use. A non-empty value overrides GITLAB_PERSONAL_ACCESS_TOKEN_FILE. One of this token, GITLAB_PERSONAL_ACCESS_TOKEN_FILE, GITLAB_JOB_TOKEN, GITLAB_AUTH_COOKIE_PATH, or GITLAB_USE_OAUTH=true must be set. Create a token with the GitLab scopes the tools need, such as api or read_api. | Secret |
| GITLAB_ALLOWED_PROJECT_IDS | Optional comma-separated list of GitLab project IDs that this server is allowed to access. | |
| GITLAB_ALLOWED_PROJECT_IDS | Optional comma-separated list of GitLab project IDs that this server is allowed to access. | |
| GITLAB_API_URL | — | |
| GITLAB_API_URL | GitLab API base URL. Use https://gitlab.com/api/v4 for GitLab.com or your self-managed GitLab API URL. | |
| GITLAB_API_URL | GitLab API base URL. Use https://gitlab.com/api/v4 for GitLab.com or your self-managed GitLab API URL. | |
| GITLAB_AUTH_COOKIE_PATH | Optional path to a GitLab authentication cookie file for cookie-based authentication. | |
| GITLAB_AUTH_COOKIE_PATH | Optional path to a GitLab authentication cookie file for cookie-based authentication. | |
| GITLAB_CA_CERT_PATH | Optional path to a custom CA certificate file for self-managed GitLab instances. | |
| GITLAB_CA_CERT_PATH | Optional path to a custom CA certificate file for self-managed GitLab instances. | |
| GITLAB_DENIED_TOOLS_REGEX | Optional regular expression used to hide matching tools from the server. | |
| GITLAB_DENIED_TOOLS_REGEX | Optional regular expression used to hide matching tools from the server. | |
| GITLAB_MASKING_CONFIG | Optional path to a response-masking JSON configuration file. | |
| GITLAB_MASKING_CONFIG | Optional path to a response-masking JSON configuration file. | |
| GITLAB_MASKING_ENABLED | Set to true to mask text tool results and returned errors using built-in or configured rules. | |
| GITLAB_MASKING_ENABLED | Set to true to mask text tool results and returned errors using built-in or configured rules. | |
| GITLAB_MASKING_POLICY_FILE | Optional protected server-owned JSON file containing managed masking policies. | |
| GITLAB_MASKING_POLICY_FILE | Optional protected server-owned JSON file containing managed masking policies. | |
| GITLAB_MASKING_WORKSPACE_DIR | Directory used to resolve response-masking configuration paths. | |
| GITLAB_MASKING_WORKSPACE_DIR | Directory used to resolve response-masking configuration paths. | |
| GITLAB_MCP_OAUTH | — | |
| GITLAB_OAUTH_APP_ID | — | |
| GITLAB_OAUTH_CLIENT_ID | GitLab OAuth application ID. When GITLAB_USE_OAUTH=true, set this or GITLAB_OAUTH_TOKEN_SCRIPT. | |
| GITLAB_OAUTH_CLIENT_ID | GitLab OAuth application ID. When GITLAB_USE_OAUTH=true, set this or GITLAB_OAUTH_TOKEN_SCRIPT. | |
| GITLAB_OAUTH_TOKEN_SCRIPT | Command that prints an OAuth access token. When GITLAB_USE_OAUTH=true, set this or GITLAB_OAUTH_CLIENT_ID. | |
| GITLAB_OAUTH_TOKEN_SCRIPT | Command that prints an OAuth access token. When GITLAB_USE_OAUTH=true, set this or GITLAB_OAUTH_CLIENT_ID. | |
| GITLAB_PERMISSION_MODE | Tool exposure. Allowed values are readonly, modify, and full. Unset uses full. readonly keeps read-only tools. modify blocks delete and teardown tools. | |
| GITLAB_PERMISSION_MODE | Tool exposure. Allowed values are readonly, modify, and full. Unset uses full. readonly keeps read-only tools. modify blocks delete and teardown tools. | |
| GITLAB_PERSONAL_ACCESS_TOKEN_FILE | Path to a file that contains the personal access token. Read once at startup and trimmed. Ignored when GITLAB_PERSONAL_ACCESS_TOKEN or --token is non-empty. A missing, unreadable, or empty file stops startup. Does not replace job token, OAuth, cookie, or remote authorization. | |
| GITLAB_PERSONAL_ACCESS_TOKEN_FILE | Path to a file that contains the personal access token. Read once at startup and trimmed. Ignored when GITLAB_PERSONAL_ACCESS_TOKEN or --token is non-empty. A missing, unreadable, or empty file stops startup. Does not replace job token, OAuth, cookie, or remote authorization. | |
| GITLAB_TOOLS | Optional comma-separated list of individual tool names to add on top of enabled toolsets. | |
| GITLAB_TOOLS | Optional comma-separated list of individual tool names to add on top of enabled toolsets. | |
| GITLAB_TOOLSETS | Optional comma-separated toolset ids (projects, issues, merge_requests, …). Unset keeps the lean core default plus discover_tools. Do not set all unless you accept loading ~all schemas (~73k tokens). | |
| GITLAB_TOOLSETS | Optional comma-separated toolset ids (projects, issues, merge_requests, …). Unset keeps the lean core default plus discover_tools. Do not set all unless you accept loading ~all schemas (~73k tokens). | |
| GITLAB_TOOL_POLICY_APPROVE | Optional comma-separated list of tool names that require explicit approval before execution. | |
| GITLAB_TOOL_POLICY_APPROVE | Optional comma-separated list of tool names that require explicit approval before execution. | |
| GITLAB_TOOL_POLICY_HIDDEN | Optional comma-separated list of tool names to hide from tools/list. | |
| GITLAB_TOOL_POLICY_HIDDEN | Optional comma-separated list of tool names to hide from tools/list. | |
| GITLAB_USE_OAUTH | Set to true to start with GitLab OAuth instead of a personal access token, job token, or cookie file. | |
| GITLAB_USE_OAUTH | Set to true to start with GitLab OAuth instead of a personal access token, job token, or cookie file. | |
| MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL | — | |
| MCP_SERVER_URL | — | |
| NODE_TLS_REJECT_UNAUTHORIZED | Set to 0 only when you intentionally need to connect to a GitLab instance with invalid or self-signed TLS certificates. | |
| NODE_TLS_REJECT_UNAUTHORIZED | Set to 0 only when you intentionally need to connect to a GitLab instance with invalid or self-signed TLS certificates. | |
| STREAMABLE_HTTP | — |
Automated checks
Ran Nov 11, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubGitLab MCP Server
English | 한국어 | 简体中文 | Português (Brasil)
📖 Documentation → · llms.txt · llms-full.txt
Default: 40 tools (38 core + discover_tools + help). 288 tools exist in total (285 in toolsets + execute_graphql + discover_tools + help). Start lean; call discover_tools to activate more for this session.
Token budget: MCP clients send the whole
tools/listto the model at session start. Keep the default (~40 tools, ~12k schema tokens). Calldiscover_toolsto activate a category for this session (session-only; withOAUTH_STATELESS_MODE=truepersist a namedGITLAB_TOOLSETSlist), or use Skill + CLI and skip MCP schemas. Do not setGITLAB_TOOLSETS=all— it loads ~all tools and costs ~73k schema tokens. See tools/list size and comparison.
Install the zereight-mcp-gitlab binary first with npm install -g @zereight/mcp-gitlab, or Homebrew brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp and brew install zereight/gitlab-mcp/zereight-mcp-gitlab. Official MCP Registry listing: io.github.zereight/gitlab-mcp. One-liner: npx -y @zereight/mcp-gitlab@latest.
Without → With
| Without this MCP | With this MCP |
|---|---|
| Paste MR URLs and diffs into chat | list_merge_request_changed_files → batched get_merge_request_file_diff |
| Hunt job logs in the GitLab UI | get_pipeline_job_output with pagination |
| Re-explain the project path every turn | project_id=group%2Fproject and merge_request_iid=123 |
Three install paths
| Path | When | How |
|---|---|---|
| Local IDE | Cursor, Claude Code, Codex on your machine | stdio + PAT or local OAuth |
| Shared HTTP | Team or hosted MCP | Streamable HTTP URL + remote auth or MCP OAuth |
| Claude.ai | Claude web connectors | Public HTTPS + GITLAB_MCP_OAUTH |
Install
Install the binary first (npm install -g @zereight/mcp-gitlab, or Homebrew brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp then brew install zereight/gitlab-mcp/zereight-mcp-gitlab). Read the token without echo:
read -rs GITLAB_PERSONAL_ACCESS_TOKEN && export GITLAB_PERSONAL_ACCESS_TOKEN
# Claude Code
claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
# Codex
codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
Other clients: VS Code · GitHub Copilot · JSON clients · Cursor details
Agent paste-prompt
Copy this into an agent that can edit MCP config:
Install the GitLab MCP server (@zereight/mcp-gitlab) for this workspace.
Binary: zereight-mcp-gitlab (npm i -g @zereight/mcp-gitlab, or npx -y @zereight/mcp-gitlab@latest).
Auth: GITLAB_PERSONAL_ACCESS_TOKEN plus GITLAB_API_URL=https://gitlab.com/api/v4 (or GITLAB_USE_OAUTH=true).
Local: claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
Or: codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
Cursor: use the README deeplink or docs/clients/cursor.md.
Remote HTTP: point the client at https://mcp.example.com/mcp (Streamable HTTP). Claude.ai needs GITLAB_MCP_OAUTH on that host.
Default list: 40 tools (38 core + discover_tools + help). Call discover_tools to expand. Do not set GITLAB_TOOLSETS=all (loads ~all schemas, ~73k tokens). Do not enable the api toolset unless you accept its bypass risk.
Equal non-MCP path: npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill plus the zereight-mcp-gitlab CLI.
Remote HTTP
First-class option for a hosted or self-hosted server. Point the client at a Streamable HTTP URL:
{
"mcpServers": {
"gitlab": {
"type": "http",
"url": "https://mcp.example.com/mcp"
}
}
}
- Hosted / Claude.ai:
GITLAB_MCP_OAUTH=trueon the server (see MCP OAuth) - Per-user PAT headers:
REMOTE_AUTHORIZATION=true(see Remote Authorization) - Local Docker examples are in Usage
Skill + CLI (no MCP required)
Skill + CLI is an equal path, not a fallback. Same workflows, full payloads in a terminal, no MCP registration.
npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill
zereight-mcp-gitlab user whoami
zereight-mcp-gitlab mr list
See CLI without MCP and skills/gitlab-mcp/.
MCP vs Human CLI
| Use MCP when | Use the CLI when |
|---|---|
| The agent needs structured tools in chat | You need the full payload (diffs, logs, artifacts) |
jmespath or compact results are enough |
GITLAB_MCP_COMPACT_RESULTS is on and you want the rest in a terminal |
| You already registered the server | You have a PAT or ran auth and do not want MCP |
Human CLI is never compacted. Destructive tools and GITLAB_TOOL_POLICY_APPROVE tools need --yes.
Tips
project_id is a numeric ID or a URL-encoded path. Example: group group, project project, merge request !123 → project_id=group%2Fproject, merge_request_iid=123. Nested groups use %2F between every segment (group%2Fsubgroup%2Fproject).
FAQ
How do I authenticate? Local desktop: GITLAB_PERSONAL_ACCESS_TOKEN (or GITLAB_PERSONAL_ACCESS_TOKEN_FILE) is the simplest. Local OAuth is GITLAB_USE_OAUTH=true. Remote Claude.ai uses GITLAB_MCP_OAUTH. Multi-user HTTP uses REMOTE_AUTHORIZATION and a per-request token header.
Why do I only see ~40 tools? The default core toolset is 38 tools plus always-on discover_tools and help. That is intentional: a client sends every listed schema to the model up front. Call discover_tools with no args to list categories, then pass a category (pipelines, wiki, …) to activate it for this session. Session-only; with OAUTH_STATELESS_MODE=true persist a named GITLAB_TOOLSETS list. Do not set GITLAB_TOOLSETS=all — it loads ~all schemas (~73k tokens) and still does not enable api.
Local OAuth vs MCP OAuth vs remote auth? Local OAuth opens a browser on the same machine as the server. MCP OAuth is for a public HTTPS server and clients such as Claude.ai. Remote authorization forwards the caller's PAT or job token; there is no OAuth dance.
How do I shrink huge replies? Pass jmespath on any tool call. Or set GITLAB_MCP_COMPACT_RESULTS=true so oversized MCP replies become a preview plus a CLI command. Use the CLI when you need the full payload.
Why is the api toolset dangerous? gitlab_api_request bypasses group/project allowlists, other tool filters, and per-tool safety checks. Prompt injection can drive it. Enable it only by listing api in GITLAB_TOOLSETS. all, discover_tools, and GITLAB_TOOLS do not.
Cursor rule / CLAUDE.md snippet
GitLab merge requests, issues, and pipelines go through this MCP (@zereight/mcp-gitlab).
Start with the default core tools. Call discover_tools to expand. Do not set GITLAB_TOOLSETS=all.
Prefer list_merge_request_changed_files, then batched get_merge_request_file_diff.
Use jmespath or compact results; use the CLI for full diffs and job logs.
@zereight/mcp-gitlab
Agent-workflow-optimized GitLab MCP — manage projects, merge requests, issues, pipelines, wiki, releases, tags, milestones, and more through stdio, SSE, and Streamable HTTP.
Supports PAT, OAuth, read-only mode, dynamic API URLs, and remote authorization for VS Code, Claude, Cursor, Copilot, and other MCP clients.
Why use this GitLab MCP?
- Default 40 tools (38
core+discover_tools+help); 288 total — start lean; calldiscover_toolsto activate more without CQRS-style grouping.GITLAB_TOOLSETS=allloads ~all schemas (~73k tokens); prefer discover-on-demand or Skill + CLI - MR 2-step review —
list_merge_request_changed_files→ batchedget_merge_request_file_diff - Agent Skill built in — workflow guidance in
skills/gitlab-mcp/ - Flexible auth — Personal Access Token, local OAuth2 browser flow, MCP OAuth proxy, and per-request remote authorization
- Multiple transports — stdio for local clients, SSE for legacy clients, and Streamable HTTP for modern remote deployments
- Client-friendly setup — examples for Claude Code, Codex, Antigravity, OpenCode, Copilot, Cline, Roo Code, Cursor, Kilo Code, and Amp Code
- Self-hosted ready — works with custom GitLab instances, proxy settings, and dynamic API URL routing
- JMESPath result filtering — optional
jmespathon tool calls (seetools/list) shrinks JSON results without changing GitLab API requests; when response masking is enabled, JMESPath runs on masked data.
How we compare
| @zereight/mcp-gitlab | GitLab MCP A (community CQRS-style) | GitLab official MCP server | |
|---|---|---|---|
| Best for | AI agent workflows | Enterprise multi-instance / grouped tools | Built into GitLab, no separate install |
| Tool model | 288 tools: 285 in toolsets + execute_graphql + discover_tools + help |
~50–60 grouped browse_* / manage_* tools |
Toolsets chosen with an HTTP header |
| MR review | 2-step batched diff | Varies | get_merge_request with diffs |
| Node.js | >=20.0.0 | Often >=24 | Node.js 20+ for stdio via mcp-remote |
| License | MIT | Varies | Part of GitLab |
tools/list size (measured 2026-11-05)
A client sends the whole tools/list result to the model at session start. Token estimate is UTF-8 bytes / 4.
| Profile | Tools | JSON bytes | Est. tokens |
|---|---|---|---|
Default (core + discover_tools + help) |
40 | 46,943 | 11,736 |
GITLAB_TOOL_PROFILE=slim |
39 | 45,935 | 11,484 |
GITLAB_TOOLSETS=all |
286 | 293,906 | 73,477 |
Re-measure with npm run build && npm run test:mock (test/tools-list-budget.test.ts) after description or schema changes.
GitLab also ships an official MCP server.
- Free, Premium, and Ultimate. Moved from Premium to Free in GitLab 19.2. Generally available in GitLab 19.5.
- On GitLab.com, a top-level group Owner allows access to the MCP server. On GitLab Self-Managed and GitLab Dedicated, an administrator controls the instance setting. Default rules are on the official page.
- Remote clients use HTTP
https://<gitlab.example.com>/api/v4/mcpwith OAuth 2.0 dynamic client registration. - stdio goes through
mcp-remoteand needs Node.js 20 or later. - Toolsets use the
X-Gitlab-Enabled-Mcp-Server-Toolsetsheader. An optionalX-Gitlab-Mcp-Server-Tool-Name-Prefixheader keeps the first 32 characters of a tool-name prefix.
Full comparison with the official GitLab MCP server →
Quick start: choose either Personal Access Token or OAuth2 setup below, install @zereight/mcp-gitlab, and use zereight-mcp-gitlab in your MCP client configuration.
Client Setup Guides
- Claude Code Setup Guide
- VS Code Setup Guide
- GitHub Copilot Setup Guide
- Codex Setup Guide
- Cursor Setup Guide
- JSON-Based MCP Clients Setup Guide - for Factory AI Droid, OpenClaw, and OpenCode style clients
- OAuth2 Authentication Setup Guide
- Environment Variables Reference
- Stateless Mode — Multi-Pod HPA
- Custom Agents and Multiple PAT Setup
Usage
Setup Overview
Authentication Methods
The server supports four authentication methods:
For local/desktop use (most common):
- Personal Access Token (
GITLAB_PERSONAL_ACCESS_TOKENorGITLAB_PERSONAL_ACCESS_TOKEN_FILE) — simplest setup - OAuth2 — Local Browser (
GITLAB_USE_OAUTH) — recommended for better security
For server/remote deployments:
- OAuth2 — MCP Proxy (
GITLAB_MCP_OAUTH) — for remote MCP clients such as Claude.ai - Remote Authorization (
REMOTE_AUTHORIZATION) — multi-user deployments where each caller provides their own token
Quick setup paths
- Claude Code: see Claude Code Setup Guide
- VS Code: see VS Code Setup Guide
- GitHub Copilot: see GitHub Copilot Setup Guide
- Codex: see Codex Setup Guide
- Cursor: see Cursor Setup Guide
- Factory AI Droid / OpenClaw / OpenCode style clients: see JSON-Based MCP Clients Setup Guide
- OAuth browser flow details: see OAuth2 Authentication Setup Guide
- OAuth without a localhost callback (SSO, remote shell, background clients): run
zereight-mcp-gitlab auth(GitLab 17.9+ device flow; 17.2–17.8 needoauth2_device_grant_flow), then start the server withGITLAB_USE_OAUTH=true. See standalone device-flow command.
For the simplest local setup, start with a Personal Access Token. For browser-based local auth, use OAuth2. For remote or multi-user deployments, continue to the MCP OAuth and Remote Authorization sections later in this README.
Install the server once:
brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp
brew install zereight/gitlab-mcp/zereight-mcp-gitlab
Or with npm:
npm install -g @zereight/mcp-gitlab
Or with Nix, by adding this flake to your own:
# flake.nix
inputs.gitlab-mcp.url = "github:zereight/gitlab-mcp";
# wherever you configure your MCP client:
command = lib.getExe inputs.gitlab-mcp.packages.${system}.default;
The store path is pinned by your lock file; update it with nix flake update gitlab-mcp.
The examples use zereight-mcp-gitlab, a less collision-prone alias for the legacy mcp-gitlab binary. If your MCP client cannot find it, use the absolute path from which zereight-mcp-gitlab.
No global install? Pin npx to the previous stable release (the version these docs recommend), for example npx -y @zereight/mcp-gitlab@2.3.23. If you always want the newest release, use npx -y @zereight/mcp-gitlab@latest instead. To try a fix merged to main before the next stable release, use npx -y @zereight/mcp-gitlab@next, a pre-release build that is not meant for production. The server prints a notice to stderr on startup when a newer version is available (disable with GITLAB_DISABLE_VERSION_CHECK=true).
Claude Desktop one-click install (MCP Bundle)
Every GitHub release after v2.3.1 ships a gitlab-mcp.mcpb MCP Bundle. Download the latest bundle and open it with Claude Desktop (or drag it into Settings → Extensions). Claude Desktop asks for your Personal Access Token (stored as a sensitive value) and lets you set GITLAB_API_URL, GITLAB_PERMISSION_MODE, GITLAB_TOOLSETS, and GITLAB_MASKING_ENABLED. No separate Node.js or npm install is needed.
To build the bundle from source, run npm run pack:mcpb (writes gitlab-mcp.mcpb).
GitLab MCP questions
How do I add GitLab MCP to Claude Code?
Run claude mcp add --env 'GITLAB_JOB_TOKEN=<YOUR_GITLAB_JOB_TOKEN>' --env 'GITLAB_PERSONAL_ACCESS_TOKEN=<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>' gitlab-mcp -- npx -y @zereight/mcp-gitlab in your terminal. Add --scope user to make it available in every project.
How do I add GitLab MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does GitLab MCP provide?
It exposes 200 tools, including merge_merge_request, approve_merge_request, unapprove_merge_request, get_merge_request_approval_state, get_merge_request_conflicts.
How do I authenticate the GitLab MCP server?
Use a personal access token via GITLAB_PERSONAL_ACCESS_TOKEN for local clients, or OAuth options for local and remote setups. Multi-user HTTP servers can forward a per-request token.
Why do I only see about 40 tools?
The default core toolset is 38 tools plus discover_tools and help to keep schema tokens low. Call discover_tools with a category name to activate more tools for the session.
How can I reduce large tool responses?
Pass a jmespath expression on any tool call to filter the JSON result. You can also enable compact results so oversized replies become a preview plus a CLI command.
How do I review a merge request's changes?
List the changed files first, then fetch diffs in batches. This avoids pasting MR URLs and diffs into chat.
How do I reference a project or merge request?
Pass a numeric project ID or URL-encoded path as project_id and the MR number as merge_request_iid. Nested groups use %2F between segments.
