GitLab MCP Server: 229 Tools, Four Auth Paths, and a Stateless Mode for Multi-Pod Deployments

What This Server Actually Solves

The problem is narrow but real: MCP clients like Claude Code, Cursor, and Copilot need a way to read and mutate GitLab resources, but the official GitLab API is large and the MCP tool surface is limited. This server maps GitLab's projects, merge requests, issues, pipelines, wiki, releases, tags, and milestones onto 229 individual MCP tools. The README frames it as "agent-workflow-optimized," and the design leans toward letting an agent discover and call exactly the tool it needs at runtime rather than forcing a fixed set. The intended user is a developer or platform team running AI coding assistants against either gitlab.com or a self-hosted instance, with a need for fine-grained control over what the agent can do. The server also claims support for multiple transports, so it covers local desktop use (stdio) and remote deployments (SSE or Streamable HTTP).

The Tool Model: 229 Granular Tools and discover_tools

The core architectural choice is granularity. Instead of ~50 to 60 grouped tools like browse_merge_requests or manage_pipelines, this server exposes 229 individual tools. The README mentions a discover_tools mechanism that lets a client start with a small toolset and activate more at runtime, without the CQRS-style grouping that other GitLab MCP servers use. That means an agent can ask for a list of merge request changed files, then batch-fetch diffs for those files in a two-step review flow. The README calls this "MR 2-step review," with list_merge_request_changed_files followed by batched get_merge_request_file_diff. The upside is precision: an agent can request exactly the data it needs, and the server doesn't bloat the initial tool list. The downside is that 229 tools is a lot for a model to choose from, and the discover_tools mechanism adds a round trip. The documentation does not state how the tool list is partitioned or how discovery is triggered, so the runtime overhead is unclear.

Four Authentication Paths and Their Trade-offs

Authentication is where this project shows the most design effort. The README lists four methods. For local desktop use, a Personal Access Token (GITLAB_PERSONAL_ACCESS_TOKEN) is the simplest, and OAuth2 with a local browser (GITLAB_USE_OAUTH) is recommended for better security. For remote deployments, there is OAuth2 via an MCP proxy (GITLAB_MCP_OAUTH) for clients like Claude.ai, and a Remote Authorization mode (REMOTE_AUTHORIZATION) where each caller supplies their own token. That last mode is the one that makes multi-user deployments feasible, because you don't have to share a single service account. The README also mentions a standalone device-flow command: zereight-mcp-gitlab auth, which works on GitLab 17.9+ natively and on 17.2 to 17.8 only if the oauth2_device_grant_flow feature flag is enabled. That version dependency is a concrete constraint you should check before adopting the OAuth route. The README also provides CLI arguments like --token and --api-url for clients that mishandle environment variables, which is a practical workaround but also a sign that configuration friction exists.

Getting It Running: Install, Config, and a Version Pin

Installation is straightforward. The README gives two paths: brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp followed by brew install zereight/gitlab-mcp/zereight-mcp-gitlab, or npm install -g @zereight/mcp-gitlab. The binary is zereight-mcp-gitlab, chosen to avoid collision with the legacy mcp-gitlab name. For clients that can't handle environment variables, the README shows a JSON config with args like --token=YOUR_GITLAB_TOKEN and --api-url=https://gitlab.com/api/v4. The environment variables include GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_API_URL, and GITLAB_PERMISSION_MODE, with values like full or readonly. The README marks GITLAB_READ_ONLY_MODE as deprecated in favor of --permission-mode=readonly. Notably, the README recommends pinning npx to a specific stable release, for example npx -y @zereight/mcp-gitlab@2.1.53, and notes that the server prints a version notice on startup unless you set GITLAB_DISABLE_VERSION_CHECK=true. That pinning advice is a sign that the project moves fast and that reproducibility matters.

A Genuine Limitation: Tool Count and Token Scoping

The most obvious limitation is the sheer number of tools. 229 tools means an MCP client has to manage a large namespace, and while discover_tools helps, it adds complexity. The README does not describe how the tool list is organized or how conflicts are avoided, so an agent could easily pick a wrong tool when names overlap. Another limitation is token scoping. The README mentions support for PAT, OAuth, and remote authorization, but it does not provide guidance on least-privilege scopes. If you give an agent a full-access PAT, it can mutate projects, merge requests, and pipelines. That is a risk in any MCP setup, but it is sharper here because the server exposes so many mutating tools. The README also mentions a stateless mode for multi-pod HPA (horizontal pod autoscaling), which suggests the server can run in Kubernetes, but the details are in a separate doc and not in the README, so you would need to read that before relying on it.

The Alternative: Grouped CQRS-Style Tools

The README includes a comparison table against a community CQRS-style GitLab MCP server. That alternative uses roughly 50 to 60 grouped tools with names like browse_* and manage_*, and it targets enterprise multi-instance or grouped tool workflows. The difference is philosophical: grouped tools reduce the surface area for an agent to learn, but they force the agent to pass parameters that select the specific resource. This server's granular tools let the agent call get_merge_request_file_diff directly, but the model must know that tool exists. The comparison also notes that the alternative often requires Node.js >=24, while this project supports Node.js >=18. That is a real compatibility advantage for this server, especially in environments with older runtimes. If your priority is a small, predictable toolset for compliance reviews, the grouped approach may be easier to audit. If your priority is agent autonomy and fine-grained operations, this server's model is more direct.

Maintenance, Licensing, and Upgrade Cost

The repository is MIT licensed, which is permissive and fits most commercial use. The recent releases show a steady cadence: v2.1.52 on August 22, v2.1.53 on August 27, and v2.1.54 on August 28, 2026. That is a fast release cycle, which means bug fixes arrive quickly but also that you should expect frequent version bumps. The README's advice to pin npx to a specific version confirms that upgrades are not always backward compatible. The server prints a version notice on startup, so you will know when you are behind, but you will need a process to test new versions before adopting them in production. The documentation is hosted separately at zereight.github.io/gitlab-mcp, and the README links to setup guides for many clients, which lowers the onboarding cost. However, the README itself is long and links out to many docs, so the actual upgrade cost depends on how much of that documentation you need to read for your deployment model.

Editorial conclusion

Adopt zereight/gitlab-mcp if you run AI agents against a self-hosted GitLab instance and want granular, on-demand tool loading without restarting the server. Skip it if you need a small, fixed toolset for enterprise compliance or if your Node.js runtime is below version 18. Before production use, verify your GitLab version supports the OAuth device flow (17.9+ natively, 17.2 to 17.8 require a feature flag), and confirm that your PAT or OAuth scopes cover exactly the projects and actions your agents will touch. The project's MIT license and active release cadence (v2.1.52 to v2.1.54 within a week) suggest maintenance is healthy, but you should pin a specific version like 2.1.53 rather than tracking latest if you need reproducible deployments.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes