# GitLab

> Full GitLab API access: repos, MRs, issues, pipelines, and registries.

[Canonical HTML page](https://top-mcps.com/mcp/gitlab) · [server.json](https://top-mcps.com/mcp/gitlab.json) · [methodology](https://top-mcps.com/about/methodology)

## Install

### Claude Desktop — `claude_desktop_config.json`

Paste under mcpServers. Fully quit and reopen Claude after editing.

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${GITLAB_PERSONAL_ACCESS_TOKEN}",
        "GITLAB_API_URL": "${GITLAB_API_URL}"
      }
    }
  }
}
```

### Claude Code — `CLI or .mcp.json`

Run from your repo. Commit .mcp.json to share with your team.

```shell
# export GITLAB_PERSONAL_ACCESS_TOKEN=glpat-your_token
# export GITLAB_API_URL=https://gitlab.com/api/v4
claude mcp add gitlab -- npx -y @zereight/mcp-gitlab
```

### Cursor — `.cursor/mcp.json`

Global path: ~/.cursor/mcp.json. Reload window after editing.

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${GITLAB_PERSONAL_ACCESS_TOKEN}",
        "GITLAB_API_URL": "${GITLAB_API_URL}"
      }
    }
  }
}
```

### VS Code — `.vscode/mcp.json`

VS Code uses the "servers" key (not "mcpServers").

```jsonc
{
  "servers": {
    "gitlab": {
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${GITLAB_PERSONAL_ACCESS_TOKEN}",
        "GITLAB_API_URL": "${GITLAB_API_URL}"
      }
    }
  }
}
```

### Windsurf — `~/.codeium/windsurf/mcp_config.json`

Open via Cascade → hammer icon → Configure.

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${GITLAB_PERSONAL_ACCESS_TOKEN}",
        "GITLAB_API_URL": "${GITLAB_API_URL}"
      }
    }
  }
}
```

### Cline — `cline_mcp_settings.json`

Open via the Cline sidebar → MCP Servers → Edit.

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${GITLAB_PERSONAL_ACCESS_TOKEN}",
        "GITLAB_API_URL": "${GITLAB_API_URL}"
      }
    }
  }
}
```

### Continue — `~/.continue/config.json`

Continue uses modelContextProtocolServers with a transport block.

```json
{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": [
            "-y",
            "@zereight/mcp-gitlab"
          ],
          "env": {
            "GITLAB_PERSONAL_ACCESS_TOKEN": "${GITLAB_PERSONAL_ACCESS_TOKEN}",
            "GITLAB_API_URL": "${GITLAB_API_URL}"
          }
        }
      }
    ]
  }
}
```

### Codex CLI — `~/.codex/config.toml`

Codex uses TOML. Each server is a [mcp_servers.<name>] subtable.

```shell
# ~/.codex/config.toml
[mcp_servers.gitlab]
command = "npx"
args = [
  "-y",
  "@zereight/mcp-gitlab",
]
env = { GITLAB_PERSONAL_ACCESS_TOKEN = "${GITLAB_PERSONAL_ACCESS_TOKEN}", GITLAB_API_URL = "${GITLAB_API_URL}" }
```

### Zed — `~/.config/zed/settings.json`

Zed calls them "context_servers". Settings live-reload on save.

```jsonc
{
  "context_servers": {
    "gitlab": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@zereight/mcp-gitlab"
        ]
      },
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${GITLAB_PERSONAL_ACCESS_TOKEN}",
        "GITLAB_API_URL": "${GITLAB_API_URL}"
      }
    }
  }
}
```

### ChatGPT — `ChatGPT → Apps directory`

GitLab doesn't ship a hosted HTTPS endpoint today. ChatGPT supports remote MCP servers only — to use this server in ChatGPT you'll need to deploy it to a public HTTPS URL first (e.g. via Cloudflare Workers or Vercel) or wait for an official remote build.

```none

```

## At a glance

- **Maintainer:** zereight (community)
- **Transport:** stdio
- **Auth model:** API key
- **Required secrets:** GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_API_URL
- **Supported clients:** Claude, Cursor, VS Code, Windsurf, Any MCP-compatible client
- **License:** MIT
- **Language:** TypeScript
- **Latest version:** latest
- **Last verified:** 2026-05-06
- **GitHub stars:** 1,480 (fetched 2026-05-11T09:29:10.755Z)
- **Score:** 82/100 (rubric 2026-04 — see https://top-mcps.com/about/methodology)
- **Source:** https://github.com/zereight/gitlab-mcp

## Tools & permissions

| Tool | Description | Args | Side effects |
|------|-------------|------|--------------|
| `list_projects` | List projects the token has access to. | `—` | read |
| `get_file_contents` | Read a file from a project at a given path and ref. | `project_id: string, file_path: string, ref?: string` | read |
| `search_code` | Search code across projects. | `q: string` | read |
| `create_merge_request` | Open a merge request. | `project_id: string, source_branch: string, target_branch: string, title: string` | write |
| `merge_merge_request` | Merge an open MR that satisfies the project's merge requirements. | `project_id: string, merge_request_iid: number` | write |
| `create_issue` | Open a new issue on a project. | `project_id: string, title: string, description?: string` | write |
| `get_pipeline` | Fetch pipeline status and jobs. | `project_id: string, pipeline_id: number` | read |

## Security & scope

- **Access scope:** read-write
- **Sandbox:** Authenticates to the GitLab API using the personal access token in `GITLAB_PERSONAL_ACCESS_TOKEN`. The blast radius equals the token scope — the MCP has whatever project, MR, issue, and admin permissions the token grants.
- **Gotchas:**
  - Self-hosted instances often have different scope semantics than gitlab.com — verify in your instance's admin docs before assuming a scope is read-only.
  - Branch protection and merge rules apply server-side; unprotected branches let an agent push directly to default branches.

## Quick answer

**What it does.** Provides access to GitLab projects, merge requests, issues, commits, branches, pipelines, and code search via the GitLab REST API.

**Best for:**
- Merge request review and management
- Issue triage on GitLab projects
- Code search across self-hosted instances
- Pipeline status monitoring
- Container-registry inspection

**Not for:**
- GitHub workflows
- Repos that span both GitHub and GitLab without a clear primary

## Recipes

### Open a draft MR that bumps a dependency

```
On the GitLab project `my-group/my-app`, open a draft merge request from a new branch `bump-axios` that updates axios to the latest patch version in package.json and runs the test pipeline. Do not merge — leave it draft for review.
```

_Tested with: Claude Desktop, Claude Code, Cursor_

## Description

The GitLab MCP connects AI models directly to the GitLab API. Read repository contents, manage merge requests, file issues, monitor pipelines, and search code across projects. Mirrors the GitHub MCP's feature set for teams that run on GitLab — self-hosted or gitlab.com.

## Why it matters

GitHub MCPs are everywhere; GitLab MCPs are not, despite GitLab being the default for many enterprise and self-hosted environments. This server fills the gap.

## Key features

- Full GitLab REST API access
- Self-hosted and gitlab.com support
- MR and issue management
- Pipeline status
- Code search
- Container registry queries

## FAQ

### Does it work with self-hosted GitLab?

Yes. Set `GITLAB_API_URL` to your instance's API root (e.g. `https://gitlab.mycompany.com/api/v4`) alongside the personal access token. The MCP routes every call to that host.

### What scopes should the GitLab token have?

For read-only code exploration: `read_api`. For MR and issue work add `api`. For private project access add `read_repository`. Start with `read_api` and expand only when the agent reports a 403 — least-privilege still matters.

### Can it merge MRs?

Yes, when the token has `api` scope and the MR meets the project's merge requirements (approvals, pipelines passing). The MCP respects GitLab's merge protection — if the rules block the merge, the call returns the same error a human would see.

### Is it official?

No — it is a community-maintained server. GitLab has not shipped a first-party MCP yet. The community server is the practical default in the meantime.

### How does it compare to the GitHub MCP?

Feature parity is close: repo browsing, MR/PR management, issue triage, code search, pipeline status. The naming differs (MR vs PR, projects vs repos) and GitLab's API surfaces a few extra primitives like container registries and runners that the MCP exposes too.

## Changelog

- **2026-05-06** — Refreshed install snippets and fact sheet; verified for 2026.
- **2025-02-20** — Initial directory listing.