gitlab-mcp

gitlab-mcp

A Model Context Protocol server for GitLab, written in Go. Authenticates with a Personal Access Token (PAT) and exposes a curated REST + GraphQL tool surface to MCP-aware clients (Cursor, Claude Desktop, custom agents, etc.).

Built on:

• the official MCP Go SDK
• GitLab client-go v2

Features

• PAT auth against any GitLab instance (gitlab.com, self-managed, on-prem).
• Two transports: stdio (default for desktop clients) and streamable HTTP (/mcp).
• ~100 tools across projects, repository, MRs, MR notes/threads/draft notes, issues + notes, labels, milestones, releases, pipelines, jobs, artifacts, deployments, environments, wiki, search, webhooks, work items / GraphQL, and Markdown rendering.
• Read-only mode (GITLAB_READ_ONLY_MODE=true) for safe agent workflows; every mutating tool is gated and not registered when read-only is on.
• Feature gates for heavy or rarely-used surfaces: USE_PIPELINE, USE_MILESTONE, USE_GITLAB_WIKI.
• Project allowlist (GITLAB_ALLOWED_PROJECT_IDS) to restrict which projects an agent can act on.
• Self-managed friendly: custom CA bundle (GITLAB_CA_CERT_PATH), proxy support, optional TLS skip for dev.
• Container image (multi-stage Go + Alpine runtime) and cross-platform release builds via GoReleaser (binaries, SHA256SUMS, and multi-arch GHCR images).

See docs/tools.md for the full tool catalog.

Install

Pre-built binaries

Download from the Releases page (Linux / macOS / Windows, amd64 / arm64).

From source

Requires Go 1.25+.

git clone https://github.com/vgromanov/gitlab-mcp.git
cd gitlab-mcp
make build              # binary at ./bin/gitlab-mcp
# or:
go install github.com/vgromanov/gitlab-mcp/cmd/gitlab-mcp@latest

Docker

docker build -t gitlab-mcp .
docker run --rm -i \
  -e GITLAB_PERSONAL_ACCESS_TOKEN \
  -e GITLAB_API_URL \
  gitlab-mcp

The default Dockerfile produces a small Alpine 3.21 runtime image with ca-certificates, running as an unprivileged user (nonroot, UID 65532). Tagged releases also publish multi-arch images to ghcr.io/vgromanov/gitlab-mcp (see .goreleaser.yaml).

Quick start

stdio (default)

export GITLAB_PERSONAL_ACCESS_TOKEN=glpat-...
export GITLAB_API_URL=https://gitlab.com/api/v4    # optional; this is the default
gitlab-mcp

Streamable HTTP

export STREAMABLE_HTTP=true
export HOST=127.0.0.1
export PORT=3002
gitlab-mcp
# -> POST/GET MCP frames at http://127.0.0.1:3002/mcp

.env file

A .env in the working directory is auto-loaded (via joho/godotenv). See .env.example.

Configuration

All options are settable via environment variable or CLI flag. CLI flags win when explicitly passed.

See docs/configuration.md for examples and trade-offs.

PAT scopes

The minimum scope is read_api. For mutating tools, grant api. To use release-asset upload or wiki edits, ensure the token has the matching project / group permissions.

Documentation

• Architecture: docs/architecture.md
• Configuration: docs/configuration.md
• Tool catalog: docs/tools.md
• Release checklist: docs/release.md
• Contributing: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security: SECURITY.md

Client setup

Cursor / Claude Desktop (stdio)

{
  "mcpServers": {
    "gitlab": {
      "command": "gitlab-mcp",
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${env:GITLAB_PERSONAL_ACCESS_TOKEN}",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_READ_ONLY_MODE": "true"
      }
    }
  }
}

Streamable HTTP client

Point your MCP client at http://HOST:PORT/mcp. Run the server with STREAMABLE_HTTP=true and bind to 127.0.0.1 unless you also put a TLS-terminating reverse proxy in front.

Tool surface (overview)

The full machine-readable list is in docs/tools.md. Mutating tools are suppressed when GITLAB_READ_ONLY_MODE=true.

Development

make test                 # unit tests
make race                 # race detector (same packages as CI)
make lint                 # go vet + gofmt check
make test-integration     # needs .env with PAT (build tag: integration)
make build                # ./bin/gitlab-mcp
make dist                 # linux/darwin × amd64/arm64 into dist/
make build-all            # cross-compile including windows/amd64
make docker               # build local image

Architecture notes: docs/architecture.md. Contribution guide: CONTRIBUTING.md.

Security

If you find a vulnerability, please follow SECURITY.md — do not file a public issue.

Operational guidance:

• Treat the PAT as a secret; never commit .env.
• Prefer GITLAB_READ_ONLY_MODE=true for any agent that doesn't need to write.
• Use GITLAB_ALLOWED_PROJECT_IDS to scope agent reach.
• Bind streamable HTTP to loopback unless you front it with TLS + auth.

License

MIT.

Acknowledgements

• modelcontextprotocol/go-sdk
• gitlab-org/api/client-go
• Prior art and tool naming conventions from the broader MCP ecosystem.