# GitLab MCP server

> Lets an AI client manage GitLab projects, merge requests, issues, pipelines, wikis and releases through the GitLab API.

- Repository: https://github.com/zereight/gitlab-mcp
- Page: https://hostedmcp.org/servers/zereight/gitlab-mcp
- Transport: stdio
- Stars: 2105
- License: MIT
- Latest version: 2.3.28

## Install

### Claude Code

```sh
claude mcp add --env 'GITLAB_JOB_TOKEN=<YOUR_GITLAB_JOB_TOKEN>' --env 'GITLAB_PERSONAL_ACCESS_TOKEN=<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>' gitlab-mcp -- npx -y @zereight/mcp-gitlab
```

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

```json
{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab"
      ],
      "env": {
        "GITLAB_JOB_TOKEN": "<YOUR_GITLAB_JOB_TOKEN>",
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>"
      }
    }
  }
}
```

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

```json
{
  "servers": {
    "gitlab-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab"
      ],
      "env": {
        "GITLAB_JOB_TOKEN": "<YOUR_GITLAB_JOB_TOKEN>",
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"gitlab-mcp","type":"stdio","command":"npx","args":["-y","@zereight/mcp-gitlab"],"env":{"GITLAB_JOB_TOKEN":"<YOUR_GITLAB_JOB_TOKEN>","GITLAB_PERSONAL_ACCESS_TOKEN":"<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>"}}'
```

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

```json
{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab"
      ],
      "env": {
        "GITLAB_JOB_TOKEN": "<YOUR_GITLAB_JOB_TOKEN>",
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add gitlab-mcp --env 'GITLAB_JOB_TOKEN=<YOUR_GITLAB_JOB_TOKEN>' --env 'GITLAB_JOB_TOKEN=<YOUR_GITLAB_JOB_TOKEN>' --env 'GITLAB_PERSONAL_ACCESS_TOKEN=<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>' --env 'GITLAB_PERSONAL_ACCESS_TOKEN=<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>' -- npx -y @zereight/mcp-gitlab
```

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

```toml
[mcp_servers.gitlab-mcp]
command = "npx"
args = ["-y", "@zereight/mcp-gitlab"]

[mcp_servers.gitlab-mcp.env]
GITLAB_JOB_TOKEN = "<YOUR_GITLAB_JOB_TOKEN>"
GITLAB_PERSONAL_ACCESS_TOKEN = "<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'GITLAB_JOB_TOKEN=<YOUR_GITLAB_JOB_TOKEN>' -e 'GITLAB_JOB_TOKEN=<YOUR_GITLAB_JOB_TOKEN>' -e 'GITLAB_PERSONAL_ACCESS_TOKEN=<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>' -e 'GITLAB_PERSONAL_ACCESS_TOKEN=<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>' gitlab-mcp npx -- -y @zereight/mcp-gitlab
```

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

```json
{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab"
      ],
      "env": {
        "GITLAB_JOB_TOKEN": "<YOUR_GITLAB_JOB_TOKEN>",
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `GITLAB_JOB_TOKEN` | no | yes | Optional GitLab CI job token to use instead of a personal access token when running inside GitLab CI. |
| `GITLAB_JOB_TOKEN` | no | yes | Optional GitLab CI job token to use instead of a personal access token when running inside GitLab CI. |
| `GITLAB_PERSONAL_ACCESS_TOKEN` | no | yes | GitLab personal access token for local stdio use. A non-empty value overrides GITLAB_PERSONAL_ACCESS_TOKEN_FILE. One of this token, GITLAB_PERSONAL_ACCESS_TOKEN_FILE, GITLAB_JOB_TOKEN, GITLAB_AUTH_COOKIE_PATH, or GITLAB_USE_OAUTH=true must be set. Create a token with the GitLab scopes the tools need, such as api or read_api. |
| `GITLAB_PERSONAL_ACCESS_TOKEN` | no | yes | GitLab personal access token for local stdio use. A non-empty value overrides GITLAB_PERSONAL_ACCESS_TOKEN_FILE. One of this token, GITLAB_PERSONAL_ACCESS_TOKEN_FILE, GITLAB_JOB_TOKEN, GITLAB_AUTH_COOKIE_PATH, or GITLAB_USE_OAUTH=true must be set. Create a token with the GitLab scopes the tools need, such as api or read_api. |
| `GITLAB_ALLOWED_PROJECT_IDS` | no | no | Optional comma-separated list of GitLab project IDs that this server is allowed to access. |
| `GITLAB_ALLOWED_PROJECT_IDS` | no | no | Optional comma-separated list of GitLab project IDs that this server is allowed to access. |
| `GITLAB_API_URL` | no | no |  |
| `GITLAB_API_URL` | no | no | GitLab API base URL. Use https://gitlab.com/api/v4 for GitLab.com or your self-managed GitLab API URL. |
| `GITLAB_API_URL` | no | no | GitLab API base URL. Use https://gitlab.com/api/v4 for GitLab.com or your self-managed GitLab API URL. |
| `GITLAB_AUTH_COOKIE_PATH` | no | no | Optional path to a GitLab authentication cookie file for cookie-based authentication. |
| `GITLAB_AUTH_COOKIE_PATH` | no | no | Optional path to a GitLab authentication cookie file for cookie-based authentication. |
| `GITLAB_CA_CERT_PATH` | no | no | Optional path to a custom CA certificate file for self-managed GitLab instances. |
| `GITLAB_CA_CERT_PATH` | no | no | Optional path to a custom CA certificate file for self-managed GitLab instances. |
| `GITLAB_DENIED_TOOLS_REGEX` | no | no | Optional regular expression used to hide matching tools from the server. |
| `GITLAB_DENIED_TOOLS_REGEX` | no | no | Optional regular expression used to hide matching tools from the server. |
| `GITLAB_MASKING_CONFIG` | no | no | Optional path to a response-masking JSON configuration file. |
| `GITLAB_MASKING_CONFIG` | no | no | Optional path to a response-masking JSON configuration file. |
| `GITLAB_MASKING_ENABLED` | no | no | Set to true to mask text tool results and returned errors using built-in or configured rules. |
| `GITLAB_MASKING_ENABLED` | no | no | Set to true to mask text tool results and returned errors using built-in or configured rules. |
| `GITLAB_MASKING_POLICY_FILE` | no | no | Optional protected server-owned JSON file containing managed masking policies. |
| `GITLAB_MASKING_POLICY_FILE` | no | no | Optional protected server-owned JSON file containing managed masking policies. |
| `GITLAB_MASKING_WORKSPACE_DIR` | no | no | Directory used to resolve response-masking configuration paths. |
| `GITLAB_MASKING_WORKSPACE_DIR` | no | no | Directory used to resolve response-masking configuration paths. |
| `GITLAB_MCP_OAUTH` | no | no |  |
| `GITLAB_OAUTH_APP_ID` | no | no |  |
| `GITLAB_OAUTH_CLIENT_ID` | no | no | GitLab OAuth application ID. When GITLAB_USE_OAUTH=true, set this or GITLAB_OAUTH_TOKEN_SCRIPT. |
| `GITLAB_OAUTH_CLIENT_ID` | no | no | GitLab OAuth application ID. When GITLAB_USE_OAUTH=true, set this or GITLAB_OAUTH_TOKEN_SCRIPT. |
| `GITLAB_OAUTH_TOKEN_SCRIPT` | no | no | Command that prints an OAuth access token. When GITLAB_USE_OAUTH=true, set this or GITLAB_OAUTH_CLIENT_ID. |
| `GITLAB_OAUTH_TOKEN_SCRIPT` | no | no | Command that prints an OAuth access token. When GITLAB_USE_OAUTH=true, set this or GITLAB_OAUTH_CLIENT_ID. |
| `GITLAB_PERMISSION_MODE` | no | no | Tool exposure. Allowed values are readonly, modify, and full. Unset uses full. readonly keeps read-only tools. modify blocks delete and teardown tools. |
| `GITLAB_PERMISSION_MODE` | no | no | Tool exposure. Allowed values are readonly, modify, and full. Unset uses full. readonly keeps read-only tools. modify blocks delete and teardown tools. |
| `GITLAB_PERSONAL_ACCESS_TOKEN_FILE` | no | no | Path to a file that contains the personal access token. Read once at startup and trimmed. Ignored when GITLAB_PERSONAL_ACCESS_TOKEN or --token is non-empty. A missing, unreadable, or empty file stops startup. Does not replace job token, OAuth, cookie, or remote authorization. |
| `GITLAB_PERSONAL_ACCESS_TOKEN_FILE` | no | no | Path to a file that contains the personal access token. Read once at startup and trimmed. Ignored when GITLAB_PERSONAL_ACCESS_TOKEN or --token is non-empty. A missing, unreadable, or empty file stops startup. Does not replace job token, OAuth, cookie, or remote authorization. |
| `GITLAB_TOOLS` | no | no | Optional comma-separated list of individual tool names to add on top of enabled toolsets. |
| `GITLAB_TOOLS` | no | no | Optional comma-separated list of individual tool names to add on top of enabled toolsets. |
| `GITLAB_TOOLSETS` | no | no | Optional comma-separated toolset ids (projects, issues, merge_requests, …). Unset keeps the lean core default plus discover_tools. Do not set all unless you accept loading ~all schemas (~73k tokens). |
| `GITLAB_TOOLSETS` | no | no | Optional comma-separated toolset ids (projects, issues, merge_requests, …). Unset keeps the lean core default plus discover_tools. Do not set all unless you accept loading ~all schemas (~73k tokens). |
| `GITLAB_TOOL_POLICY_APPROVE` | no | no | Optional comma-separated list of tool names that require explicit approval before execution. |
| `GITLAB_TOOL_POLICY_APPROVE` | no | no | Optional comma-separated list of tool names that require explicit approval before execution. |
| `GITLAB_TOOL_POLICY_HIDDEN` | no | no | Optional comma-separated list of tool names to hide from tools/list. |
| `GITLAB_TOOL_POLICY_HIDDEN` | no | no | Optional comma-separated list of tool names to hide from tools/list. |
| `GITLAB_USE_OAUTH` | no | no | Set to true to start with GitLab OAuth instead of a personal access token, job token, or cookie file. |
| `GITLAB_USE_OAUTH` | no | no | Set to true to start with GitLab OAuth instead of a personal access token, job token, or cookie file. |
| `MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL` | no | no |  |
| `MCP_SERVER_URL` | no | no |  |
| `NODE_TLS_REJECT_UNAUTHORIZED` | no | no | Set to 0 only when you intentionally need to connect to a GitLab instance with invalid or self-signed TLS certificates. |
| `NODE_TLS_REJECT_UNAUTHORIZED` | no | no | Set to 0 only when you intentionally need to connect to a GitLab instance with invalid or self-signed TLS certificates. |
| `STREAMABLE_HTTP` | no | no |  |

## Tools (200)

- `merge_merge_request`
- `approve_merge_request`
- `unapprove_merge_request`
- `get_merge_request_approval_state`
- `get_merge_request_conflicts`
- `list_merge_request_pipelines`
- `execute_graphql`
- `create_or_update_file`
- `search_repositories`
- `create_repository`
- `create_group`
- `get_file_contents`
- `push_files`
- `create_issue`
- `create_merge_request`
- `fork_repository`
- `create_branch`
- `get_branch`
- `list_branches`
- `delete_branch`
- `list_protected_branches`
- `get_protected_branch`
- `protect_branch`
- `update_protected_branch`
- `unprotect_branch`
- `update_default_branch`
- `get_merge_request`
- `get_merge_request_diffs`
- `list_merge_request_changed_files`
- `list_merge_request_diffs`
- `get_merge_request_file_diff`
- `list_merge_request_versions`
- `get_merge_request_version`
- `get_branch_diffs`
- `update_merge_request`
- `create_note`
- `create_merge_request_thread`
- `resolve_merge_request_thread`
- `mr_discussions`
- `get_merge_request_discussion`
- `delete_merge_request_discussion_note`
- `update_merge_request_discussion_note`
- `create_merge_request_discussion_note`
- `create_merge_request_note`
- `delete_merge_request_note`
- `get_merge_request_note`
- `get_merge_request_notes`
- `update_merge_request_note`
- `get_draft_note`
- `list_draft_notes`
- `create_draft_note`
- `update_draft_note`
- `delete_draft_note`
- `publish_draft_note`
- `bulk_publish_draft_notes`
- `list_merge_request_emoji_reactions`
- `list_merge_request_note_emoji_reactions`
- `create_merge_request_emoji_reaction`
- `delete_merge_request_emoji_reaction`
- `create_merge_request_note_emoji_reaction`
- `delete_merge_request_note_emoji_reaction`
- `update_issue_note`
- `create_issue_note`
- `list_issue_emoji_reactions`
- `list_issue_note_emoji_reactions`
- `create_issue_emoji_reaction`
- `delete_issue_emoji_reaction`
- `create_issue_note_emoji_reaction`
- `delete_issue_note_emoji_reaction`
- `list_issues`
- `my_issues`
- `get_issue`
- `update_issue`
- `update_issue_description_patch`
- `reorder_issue`
- `delete_issue`
- `list_todos`
- `mark_todo_done`
- `mark_all_todos_done`
- `list_issue_links`
- `list_issue_discussions`
- `get_issue_link`
- `create_issue_link`
- `delete_issue_link`
- `list_namespaces`
- `get_namespace`
- `verify_namespace`
- `get_project`
- `list_projects`
- `update_project`
- `list_project_members`
- `list_group_members`
- `list_labels`
- `get_label`
- `create_label`
- `update_label`
- `delete_label`
- `list_group_projects`
- `list_wiki_pages`
- `get_wiki_page`
- `create_wiki_page`
- `update_wiki_page`
- `delete_wiki_page`
- `list_group_wiki_pages`
- `get_group_wiki_page`
- `create_group_wiki_page`
- `update_group_wiki_page`
- `delete_group_wiki_page`
- `get_repository_tree`
- `list_pipelines`
- `get_pipeline`
- `get_pipeline_variables`
- `get_pipeline_test_report`
- `get_pipeline_test_report_summary`
- `delete_pipeline`
- `update_pipeline_metadata`
- `list_deployments`
- `get_deployment`
- `create_deployment`
- `update_deployment`
- `delete_deployment`
- `list_deployment_merge_requests`
- `approve_deployment`
- `list_environments`
- `get_environment`
- `update_environment`
- `delete_environment`
- `stop_environment`
- `stop_stale_environments`
- `delete_review_app_environments`
- `list_pipeline_triggers`
- `get_pipeline_trigger`
- `create_pipeline_trigger`
- `update_pipeline_trigger`
- `delete_pipeline_trigger`
- `trigger_pipeline`
- `list_pipeline_jobs`
- `list_pipeline_trigger_jobs`
- `get_pipeline_job`
- `get_pipeline_job_output`
- `validate_ci_lint`
- `validate_project_ci_lint`
- `list_ci_catalog_resources`
- `get_ci_catalog_resource`
- `create_pipeline`
- `retry_pipeline`
- `cancel_pipeline`
- `list_pipeline_schedules`
- `get_pipeline_schedule`
- `list_pipeline_schedule_pipelines`
- `create_pipeline_schedule`
- `update_pipeline_schedule`
- `delete_pipeline_schedule`
- `play_pipeline_schedule`
- `take_ownership_pipeline_schedule`
- `get_pipeline_schedule_variable`
- `create_pipeline_schedule_variable`
- `update_pipeline_schedule_variable`
- `delete_pipeline_schedule_variable`
- `play_pipeline_job`
- `play_pipeline_jobs`
- `retry_pipeline_job`
- `cancel_pipeline_job`
- `erase_pipeline_job`
- `wait_for_pipeline`
- `wait_for_job`
- `list_job_artifacts`
- `download_job_artifacts`
- `get_job_artifact_file`
- `list_merge_requests`
- `list_group_merge_requests`
- `list_milestones`
- `get_milestone`
- `create_milestone`
- `edit_milestone`
- `delete_milestone`
- `get_milestone_issue`
- `get_milestone_merge_requests`
- `promote_milestone`
- `get_milestone_burndown_events`
- `list_group_milestones`
- `get_group_milestone`
- `create_group_milestone`
- `edit_group_milestone`
- `delete_group_milestone`
- `get_group_milestone_issue`
- `get_group_milestone_merge_requests`
- `get_group_milestone_burndown_events`
- `get_users`
- `get_user`
- `whoami`
- `list_commits`
- `get_commit`
- `get_commit_diff`
- `get_file_blame`
- `list_commit_statuses`
- `create_commit_status`
- `list_group_iterations`
- `get_group_iteration`
- `update_group_iteration`

## FAQ

### How do I authenticate the GitLab MCP server?

Use a personal access token via GITLAB_PERSONAL_ACCESS_TOKEN for local clients, or OAuth options for local and remote setups. Multi-user HTTP servers can forward a per-request token.

### Why do I only see about 40 tools?

The default core toolset is 38 tools plus discover_tools and help to keep schema tokens low. Call discover_tools with a category name to activate more tools for the session.

### How can I reduce large tool responses?

Pass a jmespath expression on any tool call to filter the JSON result. You can also enable compact results so oversized replies become a preview plus a CLI command.

### How do I review a merge request's changes?

List the changed files first, then fetch diffs in batches. This avoids pasting MR URLs and diffs into chat.

### How do I reference a project or merge request?

Pass a numeric project ID or URL-encoded path as project_id and the MR number as merge_request_iid. Nested groups use %2F between segments.
