GitLab MCP server

gitlab-mcp

A Model Context Protocol server for the current GitLab REST API v4, written in Go with the official github.com/modelcontextprotocol/go-sdk.

It supports GitLab.com and GitLab Self-Managed, stdio and streamable HTTP transports, paginated results, and separate readonly and readwrite modes. The default is readonly.

Quick start

Using binary releases

Download a pre-built binary from the releases page:

export GITLAB_TOKEN=glpat-your-token
./gitlab-mcp --mode=readonly --transport=http --http-addr=127.0.0.1:8080 \
  --auth-token=choose-a-separate-mcp-token

Building from source

Create a GitLab personal, project, or group access token, then run:

export GITLAB_TOKEN=glpat-your-token
go run ./cmd/gitlab-mcp --mode=readonly --transport=http --http-addr=127.0.0.1:8080 \
  --auth-token=choose-a-separate-mcp-token

For a self-managed instance:

export GITLAB_BASE_URL=https://gitlab.example.com
export GITLAB_TOKEN=glpat-your-token
go run ./cmd/gitlab-mcp

GITLAB_BASE_URL is the instance URL, without /api/v4; the server appends the stable GitLab REST API path itself.

Configuration

Flags override environment variables.

Environment variable	CLI flag	Default	Description
GITLAB_BASE_URL	--gitlab-base-url	https://gitlab.com	GitLab instance URL
GITLAB_TOKEN	--gitlab-token	required	Personal, project, or group access token
GITLAB_MODE	--mode	readonly	readonly or readwrite
MCP_TRANSPORT	--transport	stdio	stdio or http
MCP_HTTP_ADDR	--http-addr	:8080	HTTP listen address
MCP_AUTH_TOKEN	--auth-token	empty	Bearer token required from HTTP MCP clients

Run gitlab-mcp --version to print the build version.

Tools

Project arguments accept either a numeric project ID or an unescaped full path such as group/subgroup/project.

Read-only tools

Tool	Purpose
gitlab_get_metadata	Get the connected GitLab version and instance metadata
gitlab_get_current_user	Get the user represented by the configured token
gitlab_list_projects	List and filter visible projects
gitlab_get_project	Get a project by ID or path
gitlab_list_issues	List issues in a project or across projects
gitlab_get_issue	Get an issue by project and IID
gitlab_list_issue_notes	List issue comments and system notes
gitlab_list_merge_requests	List merge requests in a project or across projects
gitlab_get_merge_request	Get a merge request by project and IID
gitlab_list_merge_request_diffs	List the changed files and patches in a merge request
gitlab_list_merge_request_notes	List merge request notes
gitlab_list_repository_tree	Browse a repository tree
gitlab_get_file	Read a repository file at a ref, defaulting to the default branch
gitlab_list_branches	List repository branches
gitlab_list_commits	List repository commits
gitlab_get_commit	Get one commit
gitlab_list_pipelines	List project pipelines
gitlab_get_pipeline	Get one pipeline
gitlab_list_pipeline_jobs	List jobs in a pipeline
gitlab_get_job	Get a CI/CD job by its job ID
gitlab_get_job_trace	Read a CI/CD job log (up to 1 MiB)
gitlab_search	Search globally or within a group or project

Write tools

These tools are registered only when GITLAB_MODE=readwrite or --mode=readwrite is set.

Tool	Purpose
gitlab_create_issue	Create an issue
gitlab_update_issue	Update, close, or reopen an issue
gitlab_add_issue_note	Add an issue note
gitlab_create_merge_request	Create a merge request
gitlab_update_merge_request	Update, close, or reopen a merge request
gitlab_add_merge_request_note	Add a merge request note
gitlab_accept_merge_request	Merge now or automatically when all checks pass
gitlab_create_branch	Create a branch from a ref
gitlab_create_commit	Commit a batch of file create/update/move/delete/chmod actions
gitlab_create_pipeline	Run a pipeline, optionally with variables and typed inputs
gitlab_retry_pipeline	Retry failed or canceled pipeline jobs

Issue and merge-request descriptions and notes use GitLab Flavored Markdown directly, including quick actions that can change project state. Repository files are capped at 25 MiB decoded. gitlab_get_file returns encoding: "text" for UTF-8 content and encoding: "base64" for content that is not valid UTF-8, preserving the bytes returned by GitLab. Omit ref to read from HEAD (the project's default branch).

The job tools use the GitLab Jobs API. Job logs larger than 1 MiB return a size-limit error instead of a partial log; use the job's web_url to view larger logs in GitLab.

Rate-limited 429 responses are retried up to three times for all replayable requests. Ambiguous 502, 503, and 504 responses are retried only for GET, HEAD, OPTIONS, and DELETE requests. Creates and updates are not retried on these errors, because even updates can execute quick actions more than once. Retries honor Retry-After, capped at 30 seconds per retry.

Commit actions distinguish omitted content from an empty string. Create and update actions require content; use "" to create or truncate an empty file. For move actions, omitting content preserves the file's contents, while "" empties the moved file.

Merge requests use GitLab's Draft: title convention for draft state. The merge tool accepts auto_merge to merge when all checks pass; the deprecated merge_when_pipeline_succeeds input remains available as an alias.

Authentication and token scopes

The server sends the configured token in GitLab's recommended PRIVATE-TOKEN header. Use the narrowest token and project membership that supports the tools you enable:

• readonly: use read_api; add read_repository when repository content is needed and the token type supports that scope.
• readwrite: use api, because issue, merge request, repository, and pipeline writes require API write access.

GitLab authorization still applies to every request. A token cannot access or modify resources that its user, project, or group membership cannot access.

Transports

stdio

gitlab-mcp --transport=stdio

Streamable HTTP

gitlab-mcp --transport=http --http-addr=127.0.0.1:8080 \
  --auth-token=choose-a-separate-mcp-token

HTTP clients must then send Authorization: Bearer <mcp-token>. This token protects the MCP endpoint and is separate from GITLAB_TOKEN. If no MCP auth token is configured, the HTTP endpoint has no application-level authentication. The server logs a warning when that is combined with readwrite mode.

Cross-origin browser POST requests are rejected. Native MCP clients without an Origin header and same-origin browser clients are supported.

MCP client configuration

Claude Desktop:

{
  "mcpServers": {
    "gitlab": {
      "command": "gitlab-mcp",
      "args": [],
      "env": {
        "GITLAB_BASE_URL": "https://gitlab.com",
        "GITLAB_TOKEN": "glpat-your-token",
        "GITLAB_MODE": "readonly"
      }
    }
  }
}

VS Code .vscode/mcp.json:

{
  "servers": {
    "gitlab": {
      "command": "gitlab-mcp",
      "args": [],
      "env": {
        "GITLAB_BASE_URL": "https://gitlab.com",
        "GITLAB_TOKEN": "glpat-your-token",
        "GITLAB_MODE": "readonly"
      }
    }
  }
}

Development

Requires Go 1.27.3 or newer, matching go.mod.

go build ./...
go test ./...
go vet ./...

Tests cover configuration, authentication, project-path and file-path encoding, pagination headers and links, API errors, safe retry handling, merge request drafts and diffs, binary file preservation, empty-file commit actions, job details and logs, tool mode gating, secret-safe CLI help, and end-to-end stdio and HTTP MCP connections. CI also runs the race detector and go vet.

License

MIT. See LICENSE.