gitlab-mcp
# gitlab-mcp
[MCP](https://modelcontextprotocol.io) server for GitLab — gives AI assistants access to CI pipelines, job logs, repositories, branches, merge requests, and commits through the GitLab REST API.
## Why
CI failures, pipeline status, and MR reviews are a constant context-switch. This server lets an AI assistant fetch job logs, retry failures, inspect diffs, and comment on MRs without the developer leaving their current task.
## Tools
**Pipelines & Jobs**
| Tool | Description |
|------|-------------|
| `gitlab_list_pipelines` | Recent pipelines with status |
| `gitlab_get_pipeline` | Pipeline summary + job breakdown |
| `gitlab_list_jobs` | Jobs in a specific pipeline |
| `gitlab_get_job` | Status of a single job |
| `gitlab_get_job_log` | Raw log output (with `tail` truncation) |
| `gitlab_poll_job` | Block until a job reaches a terminal state |
| `gitlab_retry_job` | Retry a failed/cancelled job |
| `gitlab_cancel_job` | Cancel a running job |
| `gitlab_retry_pipeline` | Retry all failed jobs in a pipeline |
| `gitlab_trigger_pipeline` | Trigger a new pipeline on a ref |
**Repositories & Branches**
| Tool | Description |
|------|-------------|
| `gitlab_list_projects` | Projects accessible to the token |
| `gitlab_get_project` | Project metadata |
| `gitlab_list_branches` | Branches with latest commit |
| `gitlab_get_file` | File contents at any ref |
| `gitlab_list_commits` | Commit log for a ref |
| `gitlab_get_commit` | Commit detail + diff stats |
**Merge Requests**
| Tool | Description |
|------|-------------|
| `gitlab_list_merge_requests` | Open/closed/merged MRs |
| `gitlab_get_merge_request` | Full MR detail |
| `gitlab_create_merge_request` | Open a new MR |
| `gitlab_add_mr_note` | Post a comment on an MR |
## Configuration
| Variable | Description |
|----------|-------------|
| `GITLAB_URL` | GitLab instance base URL |
| `GITLAB_TOKEN` | Personal or project access token |
| `GITLAB_DEFAULT_PROJECT` | Default project path (e.g. `group/project`) |
| `MCP_TRANSPORT` | `stdio` (default) or `sse` |
| `MCP_HOST` / `MCP_PORT` | SSE listen address |
## Run
```bash
pip install -e .
GITLAB_URL=https://gitlab.example.com GITLAB_TOKEN=... gitlab-mcp
```
## Deploy
Deployed as a systemd SSE service on Proteus. GitLab CI pushes on merge to `main`.
TDQS
Scored across 20 tools
Each tool targets a distinct operation (e.g., get_job vs get_job_log vs poll_job are clearly different). No two tools have overlapping purposes; all are well-separated.
All tools follow the consistent pattern `gitlab_verb_noun` in snake_case. Examples: gitlab_create_merge_request, gitlab_get_job_log, gitlab_trigger_pipeline. No deviations.
20 tools cover a broad yet focused scope (projects, MRs, CI/CD, files, branches). Each tool serves a clear purpose without redundancy, making the set well-scoped for a GitLab integration.
Key operations are present (create/get/list MRs, CI triggers, job management), but missing write actions like merge/close MRs, create/update files, or manage branches. This leaves notable gaps for full lifecycle coverage.