# GitLab MCP

FastMCP plugin for GitLab repository workflows. The compatibility target is GitLab 16.11.10 with the GitLab API v4, using `uv`, `fastmcp`, and `python-gitlab`.

The current catalog exposes 141 repository-centered MCP tools. Destructive tools, such as deletes, cancel, stop, unprotect, and merge acceptance, require an exact `confirm` string before they call GitLab.

## Personas

- Tech Lead: repository health, branches, merge requests, code review, approval posture, discussions, and protections.
- PO: issues, issue discussions, labels, milestones, release state, delivery status, and release links.
- Dev: repository tree, files, commits, branches, merge requests, diff versions, review discussions, and pipeline feedback.
- DevOps: pipelines, jobs, artifacts, variables, environments, releases, protected refs, and external checks.

## Configuration

Set these environment variables before starting the MCP server:

```bash
export GITLAB_URL="https://gitlab.example.com"
export GITLAB_TOKEN="glpat-..."
```

Optional variables:

- `GITLAB_OAUTH_TOKEN`
- `GITLAB_JOB_TOKEN`
- `GITLAB_SSL_VERIFY` (`true` or `false`, default `true`)
- `GITLAB_MCP_USE_SYSTEM_TRUSTSTORE` (`true` or `false`, default `true`)
- `GITLAB_TIMEOUT` (seconds, default `30`)
- `GITLAB_API_VERSION` (default `4`)
- `GITLAB_MCP_LOG_LEVEL` (`DEBUG`, `INFO`, `WARNING`, `ERROR`, default `INFO`)
- `GITLAB_MCP_LOG_JSON` (`true` or `false`, default `false`)
- `GITLAB_MCP_LOG_BACKTRACE` (`true` or `false`, default `false`)
- `GITLAB_MCP_LOG_DIAGNOSE` (`true` or `false`, default `false`)
- `GITLAB_MCP_LOG_ENQUEUE` (`true` or `false`, default `false`)
- `GITLAB_MCP_LOG_FORMAT` (Loguru format string)

Logs are written to stderr so they do not interfere with MCP stdio transport.
When TLS verification is enabled, `truststore` is used by default so Python can
validate GitLab certificates against the local operating system trust store.

## Run

```bash
uv sync --dev
uv run gitlab-mcp
```

The plugin manifest points Codex to `.mcp.json`, which runs the same command through `uv`.

## Tests

```bash
uv run pytest tests/unit -q
```

The GitLab 16.11.10 E2E test is opt-in because the container is large and slow:

```bash
GITLAB_MCP_RUN_E2E=1 uv run pytest tests/e2e -m real_gitlab -q
```

The E2E suite starts one GitLab 16.11.10 container and runs workflow tests for repository operations, issue planning, merge request review and diff versions, commit collaboration, protected tags, release links, and DevOps/release metadata.

See [docs/tool-catalog.md](docs/tool-catalog.md) for the full tool list and [docs/collaboration-tool-matrix.md](docs/collaboration-tool-matrix.md) for the role matrix behind notes and discussion tools.
See [docs/architecture.md](docs/architecture.md) for the hexagonal architecture boundaries and tool registration flow.
See [docs/mcp-exposition.md](docs/mcp-exposition.md) for the MCP safety annotations, metadata, and error handling conventions.
See [docs/python-gitlab-audit.md](docs/python-gitlab-audit.md) for the executable audit matrix against `python-gitlab` manager metadata.
See [docs/python-gitlab-tool-matrix.md](docs/python-gitlab-tool-matrix.md) for the per-tool mapping to python-gitlab functions and managers.