# GitLab MCP server

> Allows AI assistants to manage GitLab projects, merge requests, pipelines, CI/CD, issues, and code reviews via the GitLab REST API.

- Repository: https://github.com/vish288/mcp-gitlab
- Page: https://hostedmcp.org/servers/vish288/mcp-gitlab
- Transport: stdio
- Stars: 7
- License: MIT
- Latest version: 0.24.0

## Install

### Claude Code

```sh
claude mcp add --env 'GITLAB_URL=<GITLAB_URL>' --env 'GITLAB_HTTP_BEARER_TOKEN=<YOUR_GITLAB_HTTP_BEARER_TOKEN>' --env 'GITLAB_OAUTH_CLIENT_SECRET=<YOUR_GITLAB_OAUTH_CLIENT_SECRET>' --env 'GITLAB_OAUTH_JWT_KEY=<YOUR_GITLAB_OAUTH_JWT_KEY>' --env 'GITLAB_TOKEN=<YOUR_GITLAB_TOKEN>' mcp-gitlab -- uvx mcp-gitlab
```

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

```json
{
  "mcpServers": {
    "mcp-gitlab": {
      "command": "uvx",
      "args": [
        "mcp-gitlab"
      ],
      "env": {
        "GITLAB_URL": "<GITLAB_URL>",
        "GITLAB_HTTP_BEARER_TOKEN": "<YOUR_GITLAB_HTTP_BEARER_TOKEN>",
        "GITLAB_OAUTH_CLIENT_SECRET": "<YOUR_GITLAB_OAUTH_CLIENT_SECRET>",
        "GITLAB_OAUTH_JWT_KEY": "<YOUR_GITLAB_OAUTH_JWT_KEY>",
        "GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>"
      }
    }
  }
}
```

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

```json
{
  "servers": {
    "mcp-gitlab": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-gitlab"
      ],
      "env": {
        "GITLAB_URL": "<GITLAB_URL>",
        "GITLAB_HTTP_BEARER_TOKEN": "<YOUR_GITLAB_HTTP_BEARER_TOKEN>",
        "GITLAB_OAUTH_CLIENT_SECRET": "<YOUR_GITLAB_OAUTH_CLIENT_SECRET>",
        "GITLAB_OAUTH_JWT_KEY": "<YOUR_GITLAB_OAUTH_JWT_KEY>",
        "GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"mcp-gitlab","type":"stdio","command":"uvx","args":["mcp-gitlab"],"env":{"GITLAB_URL":"<GITLAB_URL>","GITLAB_HTTP_BEARER_TOKEN":"<YOUR_GITLAB_HTTP_BEARER_TOKEN>","GITLAB_OAUTH_CLIENT_SECRET":"<YOUR_GITLAB_OAUTH_CLIENT_SECRET>","GITLAB_OAUTH_JWT_KEY":"<YOUR_GITLAB_OAUTH_JWT_KEY>","GITLAB_TOKEN":"<YOUR_GITLAB_TOKEN>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "mcp-gitlab": {
      "command": "uvx",
      "args": [
        "mcp-gitlab"
      ],
      "env": {
        "GITLAB_URL": "<GITLAB_URL>",
        "GITLAB_HTTP_BEARER_TOKEN": "<YOUR_GITLAB_HTTP_BEARER_TOKEN>",
        "GITLAB_OAUTH_CLIENT_SECRET": "<YOUR_GITLAB_OAUTH_CLIENT_SECRET>",
        "GITLAB_OAUTH_JWT_KEY": "<YOUR_GITLAB_OAUTH_JWT_KEY>",
        "GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add mcp-gitlab --env 'GITLAB_URL=<GITLAB_URL>' --env 'GITLAB_HTTP_BEARER_TOKEN=<YOUR_GITLAB_HTTP_BEARER_TOKEN>' --env 'GITLAB_OAUTH_CLIENT_SECRET=<YOUR_GITLAB_OAUTH_CLIENT_SECRET>' --env 'GITLAB_OAUTH_JWT_KEY=<YOUR_GITLAB_OAUTH_JWT_KEY>' --env 'GITLAB_TOKEN=<YOUR_GITLAB_TOKEN>' -- uvx mcp-gitlab
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.mcp-gitlab]
command = "uvx"
args = ["mcp-gitlab"]

[mcp_servers.mcp-gitlab.env]
GITLAB_URL = "<GITLAB_URL>"
GITLAB_HTTP_BEARER_TOKEN = "<YOUR_GITLAB_HTTP_BEARER_TOKEN>"
GITLAB_OAUTH_CLIENT_SECRET = "<YOUR_GITLAB_OAUTH_CLIENT_SECRET>"
GITLAB_OAUTH_JWT_KEY = "<YOUR_GITLAB_OAUTH_JWT_KEY>"
GITLAB_TOKEN = "<YOUR_GITLAB_TOKEN>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'GITLAB_URL=<GITLAB_URL>' -e 'GITLAB_HTTP_BEARER_TOKEN=<YOUR_GITLAB_HTTP_BEARER_TOKEN>' -e 'GITLAB_OAUTH_CLIENT_SECRET=<YOUR_GITLAB_OAUTH_CLIENT_SECRET>' -e 'GITLAB_OAUTH_JWT_KEY=<YOUR_GITLAB_OAUTH_JWT_KEY>' -e 'GITLAB_TOKEN=<YOUR_GITLAB_TOKEN>' mcp-gitlab uvx -- mcp-gitlab
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "mcp-gitlab": {
      "command": "uvx",
      "args": [
        "mcp-gitlab"
      ],
      "env": {
        "GITLAB_URL": "<GITLAB_URL>",
        "GITLAB_HTTP_BEARER_TOKEN": "<YOUR_GITLAB_HTTP_BEARER_TOKEN>",
        "GITLAB_OAUTH_CLIENT_SECRET": "<YOUR_GITLAB_OAUTH_CLIENT_SECRET>",
        "GITLAB_OAUTH_JWT_KEY": "<YOUR_GITLAB_OAUTH_JWT_KEY>",
        "GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `GITLAB_URL` | yes | no | GitLab instance URL (e.g. https://gitlab.com) |
| `GITLAB_HTTP_BEARER_TOKEN` | no | yes | Bearer token (min 16 chars) required to bind an HTTP transport to a non-loopback host; clients send it as 'Authorization: Bearer <token>' (token mode; --auth oauth has its own sign-in) |
| `GITLAB_OAUTH_CLIENT_SECRET` | no | yes | Secret of the GitLab OAuth app (oauth mode) |
| `GITLAB_OAUTH_JWT_KEY` | no | yes | FastMCP JWT signing key, >=32 random chars (oauth mode; defaults to one derived from the client secret) |
| `GITLAB_TOKEN` | no | yes | GitLab personal access token (token mode). Optional after `mcp-gitlab auth login`; also accepts GITLAB_PAT, GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_API_TOKEN |
| `GITLAB_AUTH` | no | no | Authentication mode: token (default) or oauth (OAuth 2.1 proxy; streamable-http only) |
| `GITLAB_OAUTH_BASE_URL` | no | no | Public URL of this server, no trailing slash (oauth mode); redirect URI is <base>/auth/callback |
| `GITLAB_OAUTH_CLIENT_ID` | no | no | Application ID of the GitLab OAuth app (oauth mode, or local sign-in on a self-managed instance) |
| `GITLAB_OAUTH_SCOPES` | no | no | Space-separated GitLab scopes required on every request (oauth mode; default api) |
| `GITLAB_READ_ONLY` | no | no | Alias for MCP_READ_ONLY. Any value other than false/0/no/off/empty locks the server read-only; --read-only can only raise the lock |
| `MCP_READ_ONLY` | no | no | Locks the server read-only: write tools and write-workflow prompts are not listed and nothing lifts the lock at runtime. Shared name across the mcp-* servers; set it in the deployer's env |
| `MCP_TOOLSETS` | no | no | Comma list of tool groups to expose (code, review, ci, issues, release, admin); unset or 'all' lists every tool. Shrinks tools/list for clients with a tool budget; MCP_READ_ONLY still applies after the selection |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | no | no |  |

## Tools (91)

- `gitlab_get_project`
- `gitlab_create_project`
- `gitlab_delete_project`
- `gitlab_update_project_merge_settings`
- `gitlab_get_project_approvals`
- `gitlab_update_project_approvals`
- `gitlab_list_project_approval_rules`
- `gitlab_create_project_approval_rule`
- `gitlab_update_project_approval_rule`
- `gitlab_delete_project_approval_rule`
- `gitlab_list_mr_approval_rules`
- `gitlab_create_mr_approval_rule`
- `gitlab_update_mr_approval_rule`
- `gitlab_delete_mr_approval_rule`
- `gitlab_list_groups`
- `gitlab_get_group`
- `gitlab_share_project_with_group`
- `gitlab_unshare_project_with_group`
- `gitlab_share_group_with_group`
- `gitlab_unshare_group_with_group`
- `gitlab_list_branches`
- `gitlab_create_branch`
- `gitlab_delete_branch`
- `gitlab_list_commits`
- `gitlab_get_commit`
- `gitlab_create_commit`
- `gitlab_compare`
- `gitlab_get_file`
- `gitlab_list_tree`
- `gitlab_search_code`
- `gitlab_get_blame`
- `gitlab_list_mrs`
- `gitlab_get_mr`
- `gitlab_create_mr`
- `gitlab_update_mr`
- `gitlab_merge_mr`
- `gitlab_merge_mr_sequence`
- `gitlab_rebase_mr`
- `gitlab_mr_changes`
- `gitlab_approve_mr`
- `gitlab_unapprove_mr`
- `gitlab_get_mr_approvals`
- `gitlab_list_mr_pipelines`
- `gitlab_list_mr_commits`
- `gitlab_subscribe_mr`
- `gitlab_unsubscribe_mr`
- `gitlab_list_mr_notes`
- `gitlab_add_mr_note`
- `gitlab_delete_mr_note`
- `gitlab_update_mr_note`
- `gitlab_award_emoji`
- `gitlab_remove_emoji`
- `gitlab_list_mr_discussions`
- `gitlab_create_mr_discussion`
- `gitlab_reply_to_discussion`
- `gitlab_resolve_discussion`
- `gitlab_create_draft_note`
- `gitlab_list_draft_notes`
- `gitlab_publish_draft_notes`
- `gitlab_delete_draft_note`
- `gitlab_list_pipelines`
- `gitlab_get_pipeline`
- `gitlab_create_pipeline`
- `gitlab_retry_pipeline`
- `gitlab_cancel_pipeline`
- `gitlab_retry_job`
- `gitlab_play_job`
- `gitlab_cancel_job`
- `gitlab_get_job_log`
- `gitlab_list_tags`
- `gitlab_get_tag`
- `gitlab_create_tag`
- `gitlab_delete_tag`
- `gitlab_list_releases`
- `gitlab_get_release`
- `gitlab_create_release`
- `gitlab_update_release`
- `gitlab_delete_release`
- `gitlab_list_variables`
- `gitlab_create_variable`
- `gitlab_update_variable`
- `gitlab_delete_variable`
- `gitlab_list_group_variables`
- `gitlab_create_group_variable`
- `gitlab_update_group_variable`
- `gitlab_delete_group_variable`
- `gitlab_list_issues`
- `gitlab_get_issue`
- `gitlab_create_issue`
- `gitlab_update_issue`
- `gitlab_add_issue_comment`

## FAQ

### Can I use this with a self-hosted GitLab instance?

Yes, the server supports both GitLab.com and self-hosted GitLab instances (CE/EE).

### How can I prevent the AI from making changes to my repository?

You can run the server in a locked read-only mode by setting the MCP_READ_ONLY environment variable to true, which prevents write tools from being offered to the model.

### Do I need a GitLab Premium subscription to use this?

No, GitLab Duo or Premium subscriptions are not required to use this MCP server.

### How do I sign in if I don't have a personal access token?

You can use the command `mcp-gitlab auth login` to sign in via a public OAuth client, which stores the tokens locally.
