# GitLab MCP Server

> GitLab MCP Server is an open-source MCP server for developer tools. GitLab MCP server for projects, merge requests, issues, pipelines, wikis and releases. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, API
- **Website:** https://zereight.github.io/gitlab-mcp/
- **Repository:** https://github.com/zereight/gitlab-mcp
- **MCP Registry name:** io.github.zereight/gitlab-mcp
- **Categories:** developer tools
- **Listing updated:** 2026-11-14

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
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
```

### Claude Desktop (claude_desktop_config.json)

```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>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```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>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```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>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```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>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```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>"
      }
    }
  }
}
```

## Tools

- `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.

## 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

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/gitlab-mcp-server-4
