Allows AI assistants to manage GitLab projects, merge requests, pipelines, CI/CD, issues, and code reviews via the GitLab REST API.
Also known as vish288/mcp-gitlab, mcp-gitlab
- Stars
- 7
- Tools
- 91
- Downloads, 30 days
- 28,820
- Latest version
- 0.24.0
- Last commit
- Nov 10, 2026
- License
- MIT
What is GitLab MCP?
GitLab allows AI assistants to manage GitLab projects, merge requests, pipelines, CI/CD, issues, and code reviews via the GitLab REST API. It exposes 91 tools, such as gitlab_get_project, gitlab_create_project, gitlab_delete_project.
Summary generated from the project's README
About GitLab MCP server
Managing GitLab projects, merge requests, and CI/CD pipelines from within an AI assistant is what this server enables. It provides a comprehensive interface for developers to interact with both GitLab.com and self-hosted GitLab instances using the GitLab REST API. The server offers 91 tools, 7 resources, and 6 prompts to handle tasks ranging from code reviews and issue tracking to managing pipelines and CI/CD variables.
Users can set up the server locally via stdio or deploy it remotely using OAuth 2.1 for shared environments. For local use, you can provide a personal access token through environment variables like GITLAB_TOKEN or use the built-in auth login command to sign in via a device flow. To prevent accidental changes, the server includes a read-only mode that hides all 57 write tools, ensuring the AI can only perform read operations.
This tool is compatible with a wide range of MCP clients including Claude Desktop, Cursor, Windsurf, and VS Code Copilot. Developers can also optimize performance for clients with tool limits by using the MCP_TOOLSETS variable to expose only specific groups like code, review, or ci.
What you can do with it
- 1Restrict AI to read-only accessConfigure the server so the AI can only view project data without the ability to modify code or settings.
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_URL=<GITLAB_URL>' --env 'GITLAB_HTTP_BEARER_TOKEN=<YOUR_GITLAB_HTTP_BEARER_TOKEN>' --env 'GITLAB_OAUTH_CLIENT_SECRET=<YOUR_GITLAB_OAUTH_CLIENT_SECRET>' --env 'GITLAB_OAUTH_JWT_KEY=<YOUR_GITLAB_OAUTH_JWT_KEY>' --env 'GITLAB_TOKEN=<YOUR_GITLAB_TOKEN>' mcp-gitlab -- uvx mcp-gitlabInstall GitLab MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-gitlab": {
"command": "uvx",
"args": [
"mcp-gitlab"
],
"env": {
"GITLAB_URL": "<GITLAB_URL>",
"GITLAB_HTTP_BEARER_TOKEN": "<YOUR_GITLAB_HTTP_BEARER_TOKEN>",
"GITLAB_OAUTH_CLIENT_SECRET": "<YOUR_GITLAB_OAUTH_CLIENT_SECRET>",
"GITLAB_OAUTH_JWT_KEY": "<YOUR_GITLAB_OAUTH_JWT_KEY>",
"GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>"
}
}
}
}Install GitLab MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-gitlab": {
"type": "stdio",
"command": "uvx",
"args": [
"mcp-gitlab"
],
"env": {
"GITLAB_URL": "<GITLAB_URL>",
"GITLAB_HTTP_BEARER_TOKEN": "<YOUR_GITLAB_HTTP_BEARER_TOKEN>",
"GITLAB_OAUTH_CLIENT_SECRET": "<YOUR_GITLAB_OAUTH_CLIENT_SECRET>",
"GITLAB_OAUTH_JWT_KEY": "<YOUR_GITLAB_OAUTH_JWT_KEY>",
"GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>"
}
}
}
}Install GitLab MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-gitlab","type":"stdio","command":"uvx","args":["mcp-gitlab"],"env":{"GITLAB_URL":"<GITLAB_URL>","GITLAB_HTTP_BEARER_TOKEN":"<YOUR_GITLAB_HTTP_BEARER_TOKEN>","GITLAB_OAUTH_CLIENT_SECRET":"<YOUR_GITLAB_OAUTH_CLIENT_SECRET>","GITLAB_OAUTH_JWT_KEY":"<YOUR_GITLAB_OAUTH_JWT_KEY>","GITLAB_TOKEN":"<YOUR_GITLAB_TOKEN>"}}'Install GitLab MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-gitlab": {
"command": "uvx",
"args": [
"mcp-gitlab"
],
"env": {
"GITLAB_URL": "<GITLAB_URL>",
"GITLAB_HTTP_BEARER_TOKEN": "<YOUR_GITLAB_HTTP_BEARER_TOKEN>",
"GITLAB_OAUTH_CLIENT_SECRET": "<YOUR_GITLAB_OAUTH_CLIENT_SECRET>",
"GITLAB_OAUTH_JWT_KEY": "<YOUR_GITLAB_OAUTH_JWT_KEY>",
"GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>"
}
}
}
}Install GitLab MCP in Codex
$ codex mcp add mcp-gitlab --env 'GITLAB_URL=<GITLAB_URL>' --env 'GITLAB_HTTP_BEARER_TOKEN=<YOUR_GITLAB_HTTP_BEARER_TOKEN>' --env 'GITLAB_OAUTH_CLIENT_SECRET=<YOUR_GITLAB_OAUTH_CLIENT_SECRET>' --env 'GITLAB_OAUTH_JWT_KEY=<YOUR_GITLAB_OAUTH_JWT_KEY>' --env 'GITLAB_TOKEN=<YOUR_GITLAB_TOKEN>' -- uvx mcp-gitlabInstall GitLab MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-gitlab] command = "uvx" args = ["mcp-gitlab"] [mcp_servers.mcp-gitlab.env] GITLAB_URL = "<GITLAB_URL>" GITLAB_HTTP_BEARER_TOKEN = "<YOUR_GITLAB_HTTP_BEARER_TOKEN>" GITLAB_OAUTH_CLIENT_SECRET = "<YOUR_GITLAB_OAUTH_CLIENT_SECRET>" GITLAB_OAUTH_JWT_KEY = "<YOUR_GITLAB_OAUTH_JWT_KEY>" GITLAB_TOKEN = "<YOUR_GITLAB_TOKEN>"
Install GitLab MCP in Gemini CLI
$ gemini mcp add -s user -e 'GITLAB_URL=<GITLAB_URL>' -e 'GITLAB_HTTP_BEARER_TOKEN=<YOUR_GITLAB_HTTP_BEARER_TOKEN>' -e 'GITLAB_OAUTH_CLIENT_SECRET=<YOUR_GITLAB_OAUTH_CLIENT_SECRET>' -e 'GITLAB_OAUTH_JWT_KEY=<YOUR_GITLAB_OAUTH_JWT_KEY>' -e 'GITLAB_TOKEN=<YOUR_GITLAB_TOKEN>' mcp-gitlab uvx -- mcp-gitlabInstall GitLab MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-gitlab": {
"command": "uvx",
"args": [
"mcp-gitlab"
],
"env": {
"GITLAB_URL": "<GITLAB_URL>",
"GITLAB_HTTP_BEARER_TOKEN": "<YOUR_GITLAB_HTTP_BEARER_TOKEN>",
"GITLAB_OAUTH_CLIENT_SECRET": "<YOUR_GITLAB_OAUTH_CLIENT_SECRET>",
"GITLAB_OAUTH_JWT_KEY": "<YOUR_GITLAB_OAUTH_JWT_KEY>",
"GITLAB_TOKEN": "<YOUR_GITLAB_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 91
Detected from the READMEgitlab_get_projectgitlab_create_projectgitlab_delete_projectgitlab_update_project_merge_settingsgitlab_get_project_approvalsgitlab_update_project_approvalsgitlab_list_project_approval_rulesgitlab_create_project_approval_rulegitlab_update_project_approval_rulegitlab_delete_project_approval_rulegitlab_list_mr_approval_rulesgitlab_create_mr_approval_rule
| gitlab_get_project | — | |
| gitlab_create_project | — | |
| gitlab_delete_project | — | |
| gitlab_update_project_merge_settings | — | |
| gitlab_get_project_approvals | — | |
| gitlab_update_project_approvals | — | |
| gitlab_list_project_approval_rules | — | |
| gitlab_create_project_approval_rule | — | |
| gitlab_update_project_approval_rule | — | |
| gitlab_delete_project_approval_rule | — | |
| gitlab_list_mr_approval_rules | — | |
| gitlab_create_mr_approval_rule | — |
Show all 91 toolsShow fewer tools
gitlab_update_mr_approval_rulegitlab_delete_mr_approval_rulegitlab_list_groupsgitlab_get_groupgitlab_share_project_with_groupgitlab_unshare_project_with_groupgitlab_share_group_with_groupgitlab_unshare_group_with_groupgitlab_list_branchesgitlab_create_branchgitlab_delete_branchgitlab_list_commitsgitlab_get_commitgitlab_create_commitgitlab_comparegitlab_get_filegitlab_list_treegitlab_search_codegitlab_get_blamegitlab_list_mrsgitlab_get_mrgitlab_create_mrgitlab_update_mrgitlab_merge_mrgitlab_merge_mr_sequencegitlab_rebase_mrgitlab_mr_changesgitlab_approve_mrgitlab_unapprove_mrgitlab_get_mr_approvalsgitlab_list_mr_pipelinesgitlab_list_mr_commitsgitlab_subscribe_mrgitlab_unsubscribe_mrgitlab_list_mr_notesgitlab_add_mr_notegitlab_delete_mr_notegitlab_update_mr_notegitlab_award_emojigitlab_remove_emojigitlab_list_mr_discussionsgitlab_create_mr_discussiongitlab_reply_to_discussiongitlab_resolve_discussiongitlab_create_draft_notegitlab_list_draft_notesgitlab_publish_draft_notesgitlab_delete_draft_notegitlab_list_pipelinesgitlab_get_pipelinegitlab_create_pipelinegitlab_retry_pipelinegitlab_cancel_pipelinegitlab_retry_jobgitlab_play_jobgitlab_cancel_jobgitlab_get_job_loggitlab_list_tagsgitlab_get_taggitlab_create_taggitlab_delete_taggitlab_list_releasesgitlab_get_releasegitlab_create_releasegitlab_update_releasegitlab_delete_releasegitlab_list_variablesgitlab_create_variablegitlab_update_variablegitlab_delete_variablegitlab_list_group_variablesgitlab_create_group_variablegitlab_update_group_variablegitlab_delete_group_variablegitlab_list_issuesgitlab_get_issuegitlab_create_issuegitlab_update_issuegitlab_add_issue_comment
| gitlab_update_mr_approval_rule | — | |
| gitlab_delete_mr_approval_rule | — | |
| gitlab_list_groups | — | |
| gitlab_get_group | — | |
| gitlab_share_project_with_group | — | |
| gitlab_unshare_project_with_group | — | |
| gitlab_share_group_with_group | — | |
| gitlab_unshare_group_with_group | — | |
| gitlab_list_branches | — | |
| gitlab_create_branch | — | |
| gitlab_delete_branch | — | |
| gitlab_list_commits | — | |
| gitlab_get_commit | — | |
| gitlab_create_commit | — | |
| gitlab_compare | — | |
| gitlab_get_file | — | |
| gitlab_list_tree | — | |
| gitlab_search_code | — | |
| gitlab_get_blame | — | |
| gitlab_list_mrs | — | |
| gitlab_get_mr | — | |
| gitlab_create_mr | — | |
| gitlab_update_mr | — | |
| gitlab_merge_mr | — | |
| gitlab_merge_mr_sequence | — | |
| gitlab_rebase_mr | — | |
| gitlab_mr_changes | — | |
| gitlab_approve_mr | — | |
| gitlab_unapprove_mr | — | |
| gitlab_get_mr_approvals | — | |
| gitlab_list_mr_pipelines | — | |
| gitlab_list_mr_commits | — | |
| gitlab_subscribe_mr | — | |
| gitlab_unsubscribe_mr | — | |
| gitlab_list_mr_notes | — | |
| gitlab_add_mr_note | — | |
| gitlab_delete_mr_note | — | |
| gitlab_update_mr_note | — | |
| gitlab_award_emoji | — | |
| gitlab_remove_emoji | — | |
| gitlab_list_mr_discussions | — | |
| gitlab_create_mr_discussion | — | |
| gitlab_reply_to_discussion | — | |
| gitlab_resolve_discussion | — | |
| gitlab_create_draft_note | — | |
| gitlab_list_draft_notes | — | |
| gitlab_publish_draft_notes | — | |
| gitlab_delete_draft_note | — | |
| gitlab_list_pipelines | — | |
| gitlab_get_pipeline | — | |
| gitlab_create_pipeline | — | |
| gitlab_retry_pipeline | — | |
| gitlab_cancel_pipeline | — | |
| gitlab_retry_job | — | |
| gitlab_play_job | — | |
| gitlab_cancel_job | — | |
| gitlab_get_job_log | — | |
| gitlab_list_tags | — | |
| gitlab_get_tag | — | |
| gitlab_create_tag | — | |
| gitlab_delete_tag | — | |
| gitlab_list_releases | — | |
| gitlab_get_release | — | |
| gitlab_create_release | — | |
| gitlab_update_release | — | |
| gitlab_delete_release | — | |
| gitlab_list_variables | — | |
| gitlab_create_variable | — | |
| gitlab_update_variable | — | |
| gitlab_delete_variable | — | |
| gitlab_list_group_variables | — | |
| gitlab_create_group_variable | — | |
| gitlab_update_group_variable | — | |
| gitlab_delete_group_variable | — | |
| gitlab_list_issues | — | |
| gitlab_get_issue | — | |
| gitlab_create_issue | — | |
| gitlab_update_issue | — | |
| gitlab_add_issue_comment | — |
Configuration
GITLAB_URLRequiredGitLab instance URL (e.g. https://gitlab.com)
GITLAB_HTTP_BEARER_TOKENSecretBearer token (min 16 chars) required to bind an HTTP transport to a non-loopback host; clients send it as 'Authorization: Bearer <token>' (token mode; --auth oauth has its own sign-in)
GITLAB_OAUTH_CLIENT_SECRETSecretSecret of the GitLab OAuth app (oauth mode)
GITLAB_OAUTH_JWT_KEYSecretFastMCP JWT signing key, >=32 random chars (oauth mode; defaults to one derived from the client secret)
GITLAB_TOKENSecretGitLab personal access token (token mode). Optional after `mcp-gitlab auth login`; also accepts GITLAB_PAT, GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_API_TOKEN
GITLAB_AUTHAuthentication mode: token (default) or oauth (OAuth 2.1 proxy; streamable-http only)
GITLAB_OAUTH_BASE_URLPublic URL of this server, no trailing slash (oauth mode); redirect URI is <base>/auth/callback
GITLAB_OAUTH_CLIENT_IDApplication ID of the GitLab OAuth app (oauth mode, or local sign-in on a self-managed instance)
GITLAB_OAUTH_SCOPESSpace-separated GitLab scopes required on every request (oauth mode; default api)
GITLAB_READ_ONLYAlias for MCP_READ_ONLY. Any value other than false/0/no/off/empty locks the server read-only; --read-only can only raise the lock
MCP_READ_ONLYLocks the server read-only: write tools and write-workflow prompts are not listed and nothing lifts the lock at runtime. Shared name across the mcp-* servers; set it in the deployer's env
MCP_TOOLSETSComma list of tool groups to expose (code, review, ci, issues, release, admin); unset or 'all' lists every tool. Shrinks tools/list for clients with a tool budget; MCP_READ_ONLY still applies after the selection
OTEL_EXPORTER_OTLP_ENDPOINT
| Name | Description | |
|---|---|---|
| GITLAB_URL | GitLab instance URL (e.g. https://gitlab.com) | Required |
| GITLAB_HTTP_BEARER_TOKEN | Bearer token (min 16 chars) required to bind an HTTP transport to a non-loopback host; clients send it as 'Authorization: Bearer <token>' (token mode; --auth oauth has its own sign-in) | Secret |
| GITLAB_OAUTH_CLIENT_SECRET | Secret of the GitLab OAuth app (oauth mode) | Secret |
| GITLAB_OAUTH_JWT_KEY | FastMCP JWT signing key, >=32 random chars (oauth mode; defaults to one derived from the client secret) | Secret |
| GITLAB_TOKEN | GitLab personal access token (token mode). Optional after `mcp-gitlab auth login`; also accepts GITLAB_PAT, GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_API_TOKEN | Secret |
| GITLAB_AUTH | Authentication mode: token (default) or oauth (OAuth 2.1 proxy; streamable-http only) | |
| GITLAB_OAUTH_BASE_URL | Public URL of this server, no trailing slash (oauth mode); redirect URI is <base>/auth/callback | |
| GITLAB_OAUTH_CLIENT_ID | Application ID of the GitLab OAuth app (oauth mode, or local sign-in on a self-managed instance) | |
| GITLAB_OAUTH_SCOPES | Space-separated GitLab scopes required on every request (oauth mode; default api) | |
| GITLAB_READ_ONLY | Alias for MCP_READ_ONLY. Any value other than false/0/no/off/empty locks the server read-only; --read-only can only raise the lock | |
| MCP_READ_ONLY | Locks the server read-only: write tools and write-workflow prompts are not listed and nothing lifts the lock at runtime. Shared name across the mcp-* servers; set it in the deployer's env | |
| MCP_TOOLSETS | Comma list of tool groups to expose (code, review, ci, issues, release, admin); unset or 'all' lists every tool. Shrinks tools/list for clients with a tool budget; MCP_READ_ONLY still applies after the selection | |
| OTEL_EXPORTER_OTLP_ENDPOINT | — |
Automated checks
Ran Nov 12, 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 labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubmcp-gitlab
mcp-gitlab is a Model Context Protocol (MCP) server for the GitLab REST API. It gives AI assistants 91 tools, 7 resources, and 6 prompts to manage projects, merge requests, pipelines, CI/CD variables, approvals, issues, and code reviews. Works with Claude Desktop, Claude Code, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible client. Runs in one of two modes: with writes, or locked read-only (MCP_READ_ONLY=true) so the 57 write tools are never offered to the model.
Supports GitLab.com and self-hosted GitLab instances (CE/EE). No GitLab Duo or Premium required.
Supports the MCP 2026-07-28 specification, often called MCP 2.0, and stays compatible with 2025-11-25 clients.
Built with FastMCP 4.x, httpx, and Pydantic.
Install: uvx mcp-gitlab | PyPI | MCP Registry | Changelog
uvx mcp-gitlab # with writes
MCP_READ_ONLY=true uvx mcp-gitlab # locked read-only: write tools are not listed
1-Click Installation
Claude Code plugin — one command adds the fleet marketplace, the next installs the server, prompts for GITLAB_URL/GITLAB_TOKEN (the token is stored in the credential store, never written to a config file) with an optional MCP_READ_ONLY toggle, and keeps it updated:
claude plugin marketplace add vish288/.github
claude plugin install mcp-gitlab@vish288-mcp
💡 Tip: For other AI assistants (Claude Code, Windsurf, IntelliJ, Gemini CLI), visit the GitLab MCP Installation Gateway.
Prerequisite: Install
uvfirst (required for alluvxinstall flows). Install uv.
Claude Code
# with writes
claude mcp add gitlab -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx -- uvx mcp-gitlab
# locked read-only
claude mcp add gitlab -e MCP_READ_ONLY=true -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx -- 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
gitlabinside themcpServersobject. RemoveMCP_READ_ONLYto allow writes.
{
"mcpServers": {
"gitlab": {
"command": "uvx",
"args": ["mcp-gitlab"],
"env": {
"GITLAB_URL": "https://gitlab.example.com",
"GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
"MCP_READ_ONLY": "true"
}
}
}
}
Gemini CLI
# with writes
gemini mcp add -s user -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx gitlab uvx mcp-gitlab
# locked read-only
gemini mcp add -s user -e MCP_READ_ONLY=true -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx gitlab uvx mcp-gitlab
VS Code
Add to .vscode/mcp.json. Remove MCP_READ_ONLY to allow writes.
{
"servers": {
"gitlab": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-gitlab"],
"env": {
"GITLAB_URL": "https://gitlab.example.com",
"GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
"MCP_READ_ONLY": "true"
}
}
}
}
Codex
# with writes
codex mcp add gitlab --env GITLAB_URL=https://gitlab.example.com --env GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx -- uvx mcp-gitlab
# locked read-only
codex mcp add gitlab --env MCP_READ_ONLY=true --env GITLAB_URL=https://gitlab.example.com --env GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx -- uvx mcp-gitlab
pip / uv
uv pip install mcp-gitlab
Drop MCP_READ_ONLY to allow writes. On a shared or hosted server put it in the deployer's env, not the client config.
Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
GITLAB_URL |
Yes | - | GitLab instance URL (e.g. https://gitlab.example.com) |
GITLAB_TOKEN |
Yes, unless signed in with mcp-gitlab auth login |
- | Authentication token (see below) |
MCP_READ_ONLY |
No | false |
Shared name across the mcp-* servers. Any value other than false/0/no/off/empty locks the server read-only: the 57 write tools and write-workflow prompts are not listed, and nothing can turn it back off at runtime |
GITLAB_READ_ONLY |
No | false |
Per-server alias for MCP_READ_ONLY; either one locks the server read-only. --read-only can only raise the lock |
MCP_TOOLSETS |
No | all | Comma list of tool groups to expose (see Toolsets); unset or all lists every tool. MCP_READ_ONLY still applies after the selection |
GITLAB_HTTP_BEARER_TOKEN |
No | - | Bearer token (min 16 chars) required to bind an HTTP transport to a non-loopback host; clients send Authorization: Bearer <token>; token mode only |
GITLAB_TIMEOUT |
No | 30 |
Request timeout in seconds |
GITLAB_SSL_VERIFY |
No | true |
Set to false to skip SSL verification |
GITLAB_AUTH |
No | token |
token (PAT from env) or oauth (OAuth 2.1 proxy; see below) |
Toolsets
Clients cap how many tools they forward: Cursor warns past 40 tools across all enabled
servers. MCP_TOOLSETS (or --toolsets) shrinks tools/list to one or more named groups —
sets of the raw domain tags the tools already carry — so a single-job selection is cheap.
Unset or all lists every tool. Names are lowercase and comma-separated; an unknown name
exits 2 with the valid list. MCP_READ_ONLY still applies afterward and only ever removes
more tools (the read-only column).
| Group | Raw tags | Tools | Read-only |
|---|---|---|---|
code |
files, branches, commits | 12 | 9 |
review |
merge_requests, notes, discussions, review | 29 | 9 |
ci |
pipelines, jobs, variables | 18 | 6 |
issues |
issues | 5 | 2 |
release |
tags, releases | 9 | 4 |
admin |
projects, groups, approvals | 23 | 7 |
all (default) |
every tag | 91 | 34 |
Five tools carry two domain tags, so they are listed in both of their groups:
gitlab_list_mr_commits (code, review), gitlab_list_mr_pipelines (review, ci), and
gitlab_approve_mr / gitlab_unapprove_mr / gitlab_get_mr_approvals (review, admin).
Every single group stays under 40, and so does review,issues (34). Two pairs do not, because
the shared tools are counted once each: review,ci lists 46 tools and code,review lists
40, so both reach or pass Cursor's 40-tool warning. Pick one group per job, or leave room for
your other servers.
MCP_TOOLSETS=review uvx mcp-gitlab # MR review: 29 tools
uvx mcp-gitlab --toolsets ci # pipelines, jobs, CI/CD variables: 18 tools
MCP_TOOLSETS=issues,release uvx mcp-gitlab
Resources and prompts are unaffected by the selection.
Supported Token Types
The server checks these environment variables in order — first match wins:
GITLAB_TOKENGITLAB_PATGITLAB_PERSONAL_ACCESS_TOKENGITLAB_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 |
Sign in without a token
Use this when you run the server for yourself over stdio and have no personal
access token. mcp-gitlab auth login signs you in to GitLab as a public OAuth
client and stores the tokens locally. The server then reads them at startup and
refreshes them on its own. This is not OAuth mode; the server stays in token
mode and nothing on the MCP wire changes.
Three commands:
mcp-gitlab auth login # device flow by default; add --web for the browser flow
mcp-gitlab auth status # show the stored account, scopes, and token freshness
mcp-gitlab auth logout # revoke the token at GitLab and delete the local copy
auth login prints a code and a URL. Open the URL, enter the code, and approve.
The server then works with GITLAB_URL set and no token.
Client ID
Each sign-in needs an OAuth application ID. Resolution order: --client-id,
then GITLAB_OAUTH_CLIENT_ID, then a built-in default for https://gitlab.com.
The gitlab.com default is not registered yet. Until it is, set
GITLAB_OAUTH_CLIENT_ID or pass --client-id for gitlab.com too.
Register an app (self-managed, or gitlab.com until the default ships)
Create an application under User Settings → Applications → Add new application with these settings:
| Field | Value |
|---|---|
| Name | mcp-gitlab |
| Redirect URI | http://127.0.0.1/callback (loopback IP, no port) |
| Confidential | unchecked (public client) |
| Scopes | api, read_api |
Use 127.0.0.1, not localhost. The device flow needs GitLab 17.9 or later; on
older instances use mcp-gitlab auth login --web.
Storage and precedence
Credentials live in ~/.config/mcp-gitlab/credentials.json, one entry per
GitLab URL, mode 0600. An environment token always wins: if GITLAB_TOKEN is
set, the server uses it and ignores the stored credentials.
Pass --scopes read_api for a read-only session; the server then blocks write
tools before any API call.
OAuth 2.1 (remote deployments)
For a server shared by several people, --auth oauth turns mcp-gitlab into an
MCP 2026-07-28 resource server with GitLab as the upstream OAuth provider: each
user signs in with their own GitLab account, every request runs with that
user's token, and no personal access token is configured on the server. Use it
when you host the server once and multiple users connect to it; keep the
default --auth token for a single-user local setup.
OAuth mode requires --transport streamable-http (OAuth applies to HTTP only;
stdio keeps using the environment token).
1. Register a GitLab OAuth application (User Settings → Applications, or a
group/instance application). Set the redirect URI to <base>/auth/callback
(e.g. https://mcp.example.com/auth/callback), mark it confidential, and grant
the api scope (or read_api for a read-only deployment). Copy the
Application ID and Secret.
2. Configure the server:
| Variable | Required | Default | Description |
|---|---|---|---|
GITLAB_URL |
Yes | - | GitLab instance; also the upstream authorization server |
GITLAB_OAUTH_CLIENT_ID |
Yes | - | Application ID (oauth mode, or local sign-in) |
GITLAB_OAUTH_CLIENT_SECRET |
Yes | - | Its secret |
GITLAB_OAUTH_BASE_URL |
Yes | - | Public URL of this server, no trailing slash (e.g. https://mcp.example.com). Resource URL is <base>/mcp |
GITLAB_OAUTH_SCOPES |
No | api |
Space-separated GitLab scopes required on every request. For a read-only OAuth deployment set read_api here and MCP_READ_ONLY=true, so write tools are hidden server-wide and per-user tokens lack write scope |
GITLAB_OAUTH_JWT_KEY |
No | derived | FastMCP JWT signing key, ≥ 32 random chars. Set it in production so client registrations survive a client-secret rotation |
FASTMCP_HOME |
No | platform data dir | The encrypted token store lives at $FASTMCP_HOME/oauth-proxy/<fingerprint>/ |
GITLAB_URL=https://gitlab.com GITLAB_AUTH=oauth \
GITLAB_OAUTH_CLIENT_ID=... GITLAB_OAUTH_CLIENT_SECRET=... \
GITLAB_OAUTH_BASE_URL=https://mcp.example.com \
uvx mcp-gitlab --transport streamable-http
Point an MCP client (or the MCP Inspector, pnpm dlx @modelcontextprotocol/inspector)
at <base>/mcp; it discovers the authorization server, runs the OAuth flow, and
each tool call then uses that user's GitLab token. A read_api-only token can
read but is refused writes with an actionable hint.
Full guide, client setup and troubleshooting: docs/oauth.md.
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 |
Protocol support
mcp-gitlab implements the Model Context Protocol. It supports the 2026-07-28 specification, often called MCP 2.0. It stays compatible with 2025-11-25 clients.
- Specification: MCP 2026-07-28 (MCP 2.0). Verified over
stdioandstreamable-http. - Legacy clients: 2025-11-25 clients still work.
- Built on: FastMCP 4.x and the MCP Python SDK 2.x.
- Transports:
stdio(default) andstreamable-http(recommended for remote). Thesse(HTTP+SSE) transport still works, but the 2026-07-28 specification deprecates it. The server prints a warning when you use it. - Capabilities: tools, resources, and prompts. The server uses no roots, sampling, logging, elicitation, or resource subscriptions, so the 2026-07-28 deprecations do not affect it.
- Server identity and cache hints:
serverInforeports the installed package version and the install page aswebsiteUrl, so every response names the exact release. List results carry the 2026-07-28 cache hintsttlMs: 300000(5-minute TTL) andcacheScope: private— private becauseresources/readcan vary by the per-user token. Both are inert for clients that do not read them.
Error results
An expected failure (a 404, a 401, a validation error, or a write that reaches the read-only guard) comes back as a tool result with the protocol-level isError flag set, so a client can detect and self-correct instead of parsing an "error" key out of an otherwise successful result. In locked read-only mode the write tools are hidden, so calling one returns an Unknown tool error; the read-only envelope is the guard's own response, returned only when a client reaches a write tool anyway (a cached listing, or a future untagged tool). The body is a JSON object with error and, where it helps, status_code, body, and an actionable hint. That object is the result's text content; the error sets no structuredContent, because a strict client (the TypeScript MCP SDK) validates structuredContent against the tool's output schema even on an isError result and the schema would reject the error body. An unexpected bug is also an isError result but carries only TypeName: message text, likewise with no structuredContent.
A successful result carries the response as a JSON object in both the pretty text content and structuredContent (the object itself, not the old {"result": "<json string>"} wrapper a strict client would otherwise reject). Tools advertise no outputSchema: upstream GitLab fields pass through untyped, so a new API field never breaks a schema; a typed schema is opt-in per tool via output_schema= when a client needs one.
Tools (91)
| 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 |
| Repository Files | 4 | get file (at ref, line range), list tree, search code, blame |
| Merge Requests | 15 | list, get, create, update, merge, merge-sequence, rebase, changes, approve, unapprove, get approvals, 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 |
| Draft Notes | 4 | create (inline, auto-filled SHAs), list, publish all, delete |
| 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 |
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 |
Repository Files
| Tool | Description |
|---|---|
gitlab_get_file |
Get decoded file content at a ref (optional line range), with metadata |
gitlab_list_tree |
List repository tree entries (files and directories) at a ref |
gitlab_search_code |
Search a project's code (scope=blobs); depends on the instance's search backend |
gitlab_get_blame |
Get git blame for a file at a ref, optionally limited to a line range |
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; old_line/new_line pair resolved from the MR diff) |
gitlab_reply_to_discussion |
Reply to discussion |
gitlab_resolve_discussion |
Resolve/unresolve discussion |
Draft Notes
| Tool | Description |
|---|---|
gitlab_create_draft_note |
Create an unpublished draft note (SHAs from the MR's latest version, paired line number from its diff) |
gitlab_list_draft_notes |
List the current user's unpublished draft notes |
gitlab_publish_draft_notes |
Publish ALL pending draft notes at once ("Submit review") |
gitlab_delete_draft_note |
Delete a single unpublished draft note |
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 (last 200 lines by default; tail_lines=0 for all) |
Tags
| 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 |
GitLab MCP questions
How do I add GitLab MCP to Claude Code?
Run claude mcp add --env 'GITLAB_URL=<GITLAB_URL>' --env 'GITLAB_HTTP_BEARER_TOKEN=<YOUR_GITLAB_HTTP_BEARER_TOKEN>' --env 'GITLAB_OAUTH_CLIENT_SECRET=<YOUR_GITLAB_OAUTH_CLIENT_SECRET>' --env 'GITLAB_OAUTH_JWT_KEY=<YOUR_GITLAB_OAUTH_JWT_KEY>' --env 'GITLAB_TOKEN=<YOUR_GITLAB_TOKEN>' mcp-gitlab -- uvx 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 91 tools, including gitlab_get_project, gitlab_create_project, gitlab_delete_project, gitlab_update_project_merge_settings, gitlab_get_project_approvals.
Can I use this with a self-hosted GitLab instance?
Yes, the server supports both GitLab.com and self-hosted GitLab instances (CE/EE).
How can I prevent the AI from making changes to my repository?
You can run the server in a locked read-only mode by setting the MCP_READ_ONLY environment variable to true, which prevents write tools from being offered to the model.
Do I need a GitLab Premium subscription to use this?
No, GitLab Duo or Premium subscriptions are not required to use this MCP server.
How do I sign in if I don't have a personal access token?
You can use the command mcp-gitlab auth login to sign in via a public OAuth client, which stores the tokens locally.