# GitLab MCP server

> Allows an AI client to manage GitLab projects, merge requests, issues, pipelines, and perform global searches.

- Repository: https://github.com/crunchtools/mcp-gitlab
- Page: https://hostedmcp.org/servers/crunchtools/mcp-gitlab
- Transport: stdio
- Stars: 2
- License: AGPL-3.0
- Latest version: 0.4.1

## Install

### Claude Code

```sh
claude mcp add mcp-gitlab -- uvx mcp-gitlab-crunchtools
```

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

```json
{
  "mcpServers": {
    "mcp-gitlab": {
      "command": "uvx",
      "args": [
        "mcp-gitlab-crunchtools"
      ]
    }
  }
}
```

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

```json
{
  "servers": {
    "mcp-gitlab": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-gitlab-crunchtools"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"mcp-gitlab","type":"stdio","command":"uvx","args":["mcp-gitlab-crunchtools"]}'
```

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

```json
{
  "mcpServers": {
    "mcp-gitlab": {
      "command": "uvx",
      "args": [
        "mcp-gitlab-crunchtools"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add mcp-gitlab -- uvx mcp-gitlab-crunchtools
```

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

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

### Gemini CLI

```sh
gemini mcp add -s user mcp-gitlab uvx -- mcp-gitlab-crunchtools
```

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

```json
{
  "mcpServers": {
    "mcp-gitlab": {
      "command": "uvx",
      "args": [
        "mcp-gitlab-crunchtools"
      ]
    }
  }
}
```

## Tools (63)

- `list_projects_tool`: List GitLab projects accessible by the API token.
- `get_project_tool`: Get GitLab project details by ID or path.
- `list_project_branches_tool`: List repository branches for a GitLab project.
- `get_project_branch_tool`: Get a single repository branch.
- `list_project_commits_tool`: List repository commits for a GitLab project.
- `create_project_tool`: Create a new GitLab project.
- `delete_project_tool`: Delete a GitLab project permanently.
- `list_groups_tool`: List GitLab groups accessible by the API token.
- `get_group_tool`: Get GitLab group details by ID or path.
- `list_group_projects_tool`: List projects within a GitLab group.
- `list_merge_requests_tool`: List merge requests for a GitLab project.
- `get_merge_request_tool`: Get a single merge request by its IID.
- `create_merge_request_tool`: Create a new merge request.
- `update_merge_request_tool`: Update an existing merge request.
- `list_mr_notes_tool`: List notes (comments) on a merge request.
- `create_mr_note_tool`: Create a note (comment) on a merge request.
- `get_mr_changes_tool`: Get the changes (diff) for a merge request.
- `list_mr_discussions_tool`: List discussions (threaded comments) on a merge request. Discussions include inline code review comments with file position data.
- `create_mr_discussion_tool`: Create a new discussion on a merge request.
- `list_issues_tool`: List issues for a GitLab project.
- `get_issue_tool`: Get a single issue by its IID.
- `create_issue_tool`: Create a new issue in a GitLab project.
- `update_issue_tool`: Update an existing issue.
- `list_issue_notes_tool`: List notes (comments) on an issue.
- `create_issue_note_tool`: Create a note (comment) on an issue.
- `list_pipelines_tool`: List CI/CD pipelines for a GitLab project.
- `get_pipeline_tool`: Get a single CI/CD pipeline by ID.
- `list_pipeline_jobs_tool`: List jobs for a CI/CD pipeline.
- `get_job_log_tool`: Get the log (trace) output of a CI/CD job.
- `create_pipeline_tool`: Create (trigger) a new CI/CD pipeline.
- `retry_pipeline_tool`: Retry all failed jobs in a CI/CD pipeline.
- `cancel_pipeline_tool`: Cancel a running CI/CD pipeline.
- `delete_pipeline_tool`: Delete a CI/CD pipeline and all its jobs permanently.
- `retry_job_tool`: Retry a specific failed CI/CD job.
- `cancel_job_tool`: Cancel a running CI/CD job.
- `delete_job_tool`: Delete a CI/CD job's artifacts and trace log.
- `search_global_tool`: Search across all GitLab resources accessible by the token.
- `search_project_tool`: Search within a specific GitLab project.
- `list_repository_tree_tool`: List repository tree (files and directories).
- `get_file_tool`: Get a file from a GitLab repository. Returns file metadata and content (base64 encoded).
- `create_file_tool`: Create a new file in a GitLab repository.
- `update_file_tool`: Update an existing file in a GitLab repository.
- `create_branch_tool`: Create a new branch in a GitLab repository.
- `delete_branch_tool`: Delete a branch from a GitLab repository.
- `compare_branches_tool`: Compare two branches, tags, or commits.
- `list_labels_tool`: List labels for a GitLab project.
- `create_label_tool`: Create a new label in a GitLab project.
- `update_label_tool`: Update an existing label in a GitLab project.
- `delete_label_tool`: Delete a label from a GitLab project.
- `get_current_user_tool`: Get the currently authenticated GitLab user.
- `list_users_tool`: List GitLab users.
- `get_user_tool`: Get a specific GitLab user by ID.
- `list_releases_tool`: List releases for a GitLab project.
- `get_release_tool`: Get a single release by tag name.
- `create_release_tool`: Create a new release for a GitLab project.
- `list_milestones_tool`: List milestones for a GitLab project.
- `create_milestone_tool`: Create a new milestone in a GitLab project.
- `update_milestone_tool`: Update an existing milestone.
- `list_wiki_pages_tool`: List wiki pages for a GitLab project.
- `get_wiki_page_tool`: Get a single wiki page by slug.
- `create_wiki_page_tool`: Create a new wiki page in a GitLab project.
- `list_snippets_tool`: List snippets for a GitLab project.
- `create_snippet_tool`: Create a new snippet in a GitLab project.

## FAQ

### Does this work with self-hosted GitLab instances?

Yes, it works with gitlab.com, self-hosted, or enterprise instances via a configurable URL.

### How is my GitLab token secured?

The token is held as a SecretStr to prevent accidental logging and is only passed via environment variables.

### What permissions do I need to grant the token?

You can use the 'read_api' scope for read-only access or the 'api' scope for full access including creating and updating resources.

### Can I run this in a container?

Yes, a containerized version is available via Quay.io.
