zereight/gitlab-mcp

What is GitLab MCP Server?

gitlab-mcp is a stand‑alone Model‑Context‑Protocol (MCP) server that lets AI agents (Claude, Codex, Cursor, VS Code, Copilot, etc.) talk to a GitLab instance. It wraps the GitLab REST/GraphQL API behind the MCP interface, exposing hundreds of ready‑to‑use tools (e.g. create‑merge‑request, list‑issues, run‑pipeline, read‑wiki) that an LLM can invoke directly.

Why it exists

The official GitLab MCP server is built into GitLab and is relatively heavyweight. gitlab-mcp is a lightweight, install‑once binary that can run locally, in a container, or on a custom self‑hosted GitLab.
It is optimised for AI‑agent workflows – tools are grouped into toolsets, support two‑step MR diff review, JMESPath result filtering, and fine‑grained permission modes.
It works with many MCP clients (Claude Code, Codex, Cursor, VS Code, Copilot, JSON‑based clients) via stdio, Server‑Sent Events (SSE), or streamable HTTP.

Key Features (as described in the README)

Feature	What it means
275 tools (273 in toolsets + `execute_graphql` + `discover_tools`)	A large toolbox; you can start with a minimal core set and enable more at runtime.
2‑step MR review	First list changed files, then fetch diffs in batches – a pattern that matches how agents reason about code changes.
Agent Skill built‑in	Pre‑written “skills” (prompt‑style guidance) live under `skills/gitlab-mcp/` to help agents use the tools correctly.
Flexible auth	Personal Access Token (PAT), local OAuth2 browser flow, MCP‑proxy OAuth, or per‑request remote auth for multi‑user deployments.
Multiple transports	stdio for local clients, SSE for legacy clients, streamable HTTP for remote deployments.
Client‑friendly setup	Ready‑made install commands for Claude Code, Codex, Cursor, VS Code, Copilot, and generic JSON‑based MCP clients.
Self‑hosted ready	Works with custom GitLab URLs, proxy settings, and can be run from Docker, Homebrew, npm, or Nix.
JMESPath filtering	Optional post‑processing of tool JSON results to shrink payloads without changing the underlying GitLab request.
Permission modes	`readonly`, `modify` (no destructive deletes), or `full` – enforced per‑tool and per‑toolset.
Result compacting	Oversized tool replies can be truncated with a preview and a CLI command to fetch the full data.
Masking support	Text‑response masking for privacy‑sensitive fields.

How to get it running

Install – via npm (npm i -g @zereight/mcp-gitlab), Homebrew (brew tap zereight/gitlab-mcp && brew install zereight-mcp-gitlab), or Nix (add the flake as an input).
Provide a token – either set GITLAB_PERSONAL_ACCESS_TOKEN (or the _FILE variant) or run the built‑in OAuth device flow with zereight-mcp-gitlab auth.
Start the server – simply run zereight-mcp-gitlab. It will listen on 0.0.0.0:3002 by default.

Configure your MCP client – e.g. for 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

Similar snippets exist for VS Code, Cursor, Copilot, and generic JSON‑based clients.

When would you use it?

AI‑augmented development – let an LLM create branches, open merge requests, run CI, or fetch issue data without writing custom API calls.
Multi‑user AI assistants – remote‑auth mode lets each user present their own PAT, enabling a shared server that respects individual permissions.
Self‑hosted GitLab – the server can point at any GitLab instance (GITLAB_API_URL), making it suitable for internal enterprises.
Experimentation – because the toolset is extensible (discover_tools), you can prototype new GitLab‑related actions without modifying the server code.

Quick reference of the most useful CLI flags

Flag	Purpose
`--token <PAT>`	Override the env var for the personal access token.
`--api-url <URL>`	Point the server at a custom GitLab API endpoint.
`--permission-mode <readonly	modify
`--toolsets <list>`	Enable named groups of tools (e.g. `core,wiki,milestones`).
`--tools <tool1,tool2>`	Add individual tools on top of the default set.
`--use-wiki`, `--use-milestone`, `--use-pipeline`	Legacy flags (being deprecated) that enable the corresponding toolsets.
`--compact-results`	Truncate large tool responses and provide a CLI command to fetch the full payload.
`--masking-enabled`	Turn on response masking for privacy‑sensitive fields.

Where to learn more

Documentation site – https://zereight.github.io/gitlab-mcp/ (full guides, tool reference, auth details).
Comparison chart – shows how this server differs from the community‑style GitLab MCP A and the official GitLab MCP server.
Skill files – skills/gitlab-mcp/ contains prompt snippets that help LLMs use the tools correctly.

TL;DR

gitlab-mcp is a purpose‑built MCP server that turns GitLab into a rich toolbox for AI agents. Install the binary, give it a token, start it, and point your LLM‑powered client at it – you’ll instantly have hundreds of GitLab actions (issues, MR diffs, pipelines, wiki, releases, etc.) available via a simple, permission‑aware API.