GitLab MCP Server
GitLab MCP server for projects, merge requests, issues, pipelines, wikis and releases
- Pricing
- Open source
- Platforms
- CLI, self-hosted, API
- Runs
- Locally
- Version
- 2.3.28
- Listing updated
- 3 days ago
About GitLab MCP Server
GitLab MCP Server is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.
This server starts with a lean set of 40 tools and can grow to 288 on demand. That choice is about context cost: the README measures about 12k schema tokens for the default and about 73k with everything loaded, so a discover_tools call activates extra toolsets for the session instead.
Two tools for merge request review stand out: one lists changed files and another returns batched file diffs, and a pipeline tool returns paginated job logs. An execute_graphql tool covers anything else GitLab's GraphQL API exposes. Auth options include personal access tokens, job tokens, OAuth flows and per-request remote authorisation.
Admins can narrow it with a readonly, modify or full permission mode, an allowed project id list, a denied-tool regex and named toolsets. It works with GitLab.com and self-managed instances, over stdio, legacy SSE or Streamable HTTP, and is distributed through npm and Homebrew.
Install
Run in a terminal
claude mcp add gitlab-mcp --env GITLAB_PERSONAL_ACCESS_TOKEN='<GITLAB_PERSONAL_ACCESS_TOKEN>' --env GITLAB_JOB_TOKEN='<GITLAB_JOB_TOKEN>' -- npx -y @zereight/mcp-gitlabAdd to claude_desktop_config.json
{
"mcpServers": {
"gitlab-mcp": {
"command": "npx",
"args": [
"-y",
"@zereight/mcp-gitlab"
],
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "<GITLAB_PERSONAL_ACCESS_TOKEN>",
"GITLAB_JOB_TOKEN": "<GITLAB_JOB_TOKEN>"
}
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"gitlab-mcp": {
"command": "npx",
"args": [
"-y",
"@zereight/mcp-gitlab"
],
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "<GITLAB_PERSONAL_ACCESS_TOKEN>",
"GITLAB_JOB_TOKEN": "<GITLAB_JOB_TOKEN>"
}
}
}
}Add to .vscode/mcp.json
{
"servers": {
"gitlab-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@zereight/mcp-gitlab"
],
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "<GITLAB_PERSONAL_ACCESS_TOKEN>",
"GITLAB_JOB_TOKEN": "<GITLAB_JOB_TOKEN>"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"gitlab-mcp": {
"command": "npx",
"args": [
"-y",
"@zereight/mcp-gitlab"
],
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "<GITLAB_PERSONAL_ACCESS_TOKEN>",
"GITLAB_JOB_TOKEN": "<GITLAB_JOB_TOKEN>"
}
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"gitlab-mcp": {
"command": "npx",
"args": [
"-y",
"@zereight/mcp-gitlab"
],
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "<GITLAB_PERSONAL_ACCESS_TOKEN>",
"GITLAB_JOB_TOKEN": "<GITLAB_JOB_TOKEN>"
}
}
}
}Configuration
GITLAB_PERSONAL_ACCESS_TOKENGitLab 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_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_JOB_TOKENOptional GitLab CI job token to use instead of a personal access token when running inside GitLab CI.GITLAB_AUTH_COOKIE_PATHOptional path to a GitLab authentication cookie file for cookie-based authentication.GITLAB_USE_OAUTHSet to true to start with GitLab OAuth instead of a personal access token, job token, or cookie file.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_API_URLGitLab API base URL. Use https://gitlab.com/api/v4 for GitLab.com or your self-managed GitLab API URL.GITLAB_ALLOWED_PROJECT_IDSOptional comma-separated list of GitLab project IDs that this server is allowed to access.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_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_TOOLSOptional comma-separated list of individual tool names to add on top of enabled toolsets.GITLAB_DENIED_TOOLS_REGEXOptional regular expression used to hide matching tools from the server.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.NODE_TLS_REJECT_UNAUTHORIZEDSet to 0 only when you intentionally need to connect to a GitLab instance with invalid or self-signed TLS certificates.GITLAB_CA_CERT_PATHOptional path to a custom CA certificate file for self-managed GitLab instances.GITLAB_MASKING_ENABLEDSet to true to mask text tool results and returned errors using built-in or configured rules.GITLAB_MASKING_CONFIGOptional path to a response-masking JSON configuration file.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_PERSONAL_ACCESS_TOKENGitLab 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_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_JOB_TOKENOptional GitLab CI job token to use instead of a personal access token when running inside GitLab CI.GITLAB_AUTH_COOKIE_PATHOptional path to a GitLab authentication cookie file for cookie-based authentication.GITLAB_USE_OAUTHSet to true to start with GitLab OAuth instead of a personal access token, job token, or cookie file.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_API_URLGitLab API base URL. Use https://gitlab.com/api/v4 for GitLab.com or your self-managed GitLab API URL.GITLAB_ALLOWED_PROJECT_IDSOptional comma-separated list of GitLab project IDs that this server is allowed to access.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_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_TOOLSOptional comma-separated list of individual tool names to add on top of enabled toolsets.GITLAB_DENIED_TOOLS_REGEXOptional regular expression used to hide matching tools from the server.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.NODE_TLS_REJECT_UNAUTHORIZEDSet to 0 only when you intentionally need to connect to a GitLab instance with invalid or self-signed TLS certificates.GITLAB_CA_CERT_PATHOptional path to a custom CA certificate file for self-managed GitLab instances.GITLAB_MASKING_ENABLEDSet to true to mask text tool results and returned errors using built-in or configured rules.GITLAB_MASKING_CONFIGOptional path to a response-masking JSON configuration file.GITLAB_MASKING_POLICY_FILEOptional protected server-owned JSON file containing managed masking policies.GITLAB_MASKING_WORKSPACE_DIRDirectory used to resolve response-masking configuration paths.
Tools this server provides (5)
Taken from the project documentation; the running server may differ.
- discover_tools
- Activates more toolsets for the session.
- execute_graphql
- Runs a GitLab GraphQL query.
- list_merge_request_changed_files
- Lists files changed in a merge request.
- get_merge_request_file_diff
- Returns batched file diffs for a merge request.
- get_pipeline_job_output
- Returns pipeline job output with pagination.
What it does
- Lean default
- 40 tools by default, with more activated on request.
- Permission modes
- Readonly, modify or full tool exposure.
- Project allow list
- Restrict access to chosen project ids.
- MR review tools
- Changed-file lists and batched diffs.
- Several auth methods
- Tokens, OAuth, cookie file or remote authorisation.
- Self-managed support
- Point it at your own GitLab API URL.
Good for
- Review a merge request from chat
- Read failing pipeline job logs
- Triage and update issues
- Run an ad hoc GraphQL query
- Give a team a read-only GitLab connector
Pricing
Open source
Free open-source package
Prices change. Check zereight.github.io before you buy.
GitLab MCP Server FAQ
How many tools exist?
288 in total, with 40 loaded by default.
Does it support self-hosted GitLab?
Yes, set GITLAB_API_URL.
Can I make it read-only?
Yes, with GITLAB_PERMISSION_MODE=readonly.
How do I run it?
npx -y @zereight/mcp-gitlab@latest, or install the binary with npm or Homebrew.
Is GitLab MCP Server free?
Yes. GitLab MCP Server is open source, so you can use and self-host it for free.
How do I add GitLab MCP Server to Claude Code?
Run this command in your terminal: claude mcp add gitlab-mcp --env GITLAB_PERSONAL_ACCESS_TOKEN='<GITLAB_PERSONAL_ACCESS_TOKEN>' --env GITLAB_JOB_TOKEN='<GITLAB_JOB_TOKEN>' -- npx -y @zereight/mcp-gitlab
What are the best alternatives to GitLab MCP Server?
The closest alternatives to GitLab MCP Server are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.
Alternatives to GitLab MCP Server

REA
MCP serverCLI and MCP server that lets coding agents reverse engineer apps and binaries
Runs locally- Open source
- 464K GitHub stars
- Developer tools

Codebase Memory
MCP serverLocal MCP server that builds a code knowledge graph for AI coding agents
Runs locally- Open source
- 48.7K GitHub stars
- Knowledge and memory

GitHub
MCP serverOfficial MCP server connecting AI assistants to GitHub repos, issues and workflows
Not checked yet- Remote
- Open source
- 34.5K GitHub stars
- Developer tools

Serena MCP: the IDE for your agent
MCP serverMCP toolkit giving coding agents symbol-level code retrieval and editing
Runs locally- Open source
- 31.5K GitHub stars
- Developer tools

XERJ
MCP serverLocal search engine for AI agents with cited answers over your code and docs
Runs locally- Open source
- 19.2K GitHub stars
- Knowledge and memory

Ouroboros
MCP serverSpec-first layer that pins requirements and verifies results of AI coding agent work
Runs locally- Open source
- 6.4K GitHub stars
- Developer tools