Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
@godrix/gitlab-utils-mcp
Node.js MCP server for the GitLab REST API — built for AI agents (pipelines, merge requests, diffs, local review, and context discovery).
Version 0.3.1 — gitlab_-prefixed tools, full MR lifecycle, read-only mode, server instructions, prompts, and resources.
Prerequisites
- Node.js 18+
- GitLab PAT with
apiandread_repository(write scope for merge/comment/approve) - Git on PATH (for
repo_path, worktrees, and local review)
Quick install (npx)
No clone or local build — the published npm package includes compiled JavaScript.
Cursor / Claude Desktop (mcp.json)
{
"mcpServers": {
"gitlab-utils": {
"command": "npx",
"args": ["-y", "@godrix/gitlab-utils-mcp"],
"env": {
"GITLAB_TOKEN": "glpat-...",
"GITLAB_BASE_URL": "https://gitlab.example.com",
"GITLAB_READ_ONLY": "false"
}
}
}
}Restart your MCP client after saving. Optional variables: GITLAB_PROJECT_ID, WORKTREE_DIR.
Global install (alternative)
npm install -g @godrix/gitlab-utils-mcpThen use "command": "gitlab-utils-mcp" in mcp.json (no npx).
Environment variables
| Variable | Required | Description |
|---|---|---|
GITLAB_TOKEN | Yes | Sent as PRIVATE-TOKEN header |
GITLAB_BASE_URL | Yes | e.g. https://gitlab.example.com |
GITLAB_PROJECT_ID | No | Fallback group/repo or numeric ID |
WORKTREE_DIR | No | Default: /tmp/referencia_ao_mcp_worktree |
GITLAB_READ_ONLY | No | Default: false. When true, blocks writes (merge, comment, approve, pipeline control, prepare_review) |
Project resolution: pass project_id on a tool, or repo_path (local clone) to infer group/repo from origin, or set GITLAB_PROJECT_ID.
MR without IID: with repo_path, the current branch resolves the open MR (source_branch); errors if zero or multiple MRs match. Use gitlab_resolve_context to discover the IID.
Tools
Discovery
| Tool | Description |
|---|---|
gitlab_resolve_context | Resolve project_path, branch, and MR from repo_path |
gitlab_search_projects | Search projects accessible by the token |
Merge requests
| Tool | Description |
|---|---|
gitlab_get_merge_request | MR metadata (state, reviewers, pipeline) |
gitlab_get_mr_merge_status | Mergeability: conflicts, draft, pipeline, approvals, blockers |
gitlab_get_mr_context | Diff/changes + optional CI traces and discussions |
gitlab_get_mr_discussions | Review threads and comments |
gitlab_add_mr_inline_comment | Inline comment on a diff line |
gitlab_manage_merge_requests | list, get, create, update, approve, unapprove, comment, merge, close, reopen, mark_draft, mark_ready |
CI/CD
| Tool | Description |
|---|---|
gitlab_list_pipelines | List pipelines (by ref, MR, or status) |
gitlab_get_pipeline | Pipeline + jobs |
gitlab_get_job_trace | Job log |
gitlab_control_pipeline | list_jobs, play, retry_job, retry_pipeline, cancel_pipeline |
Repository
| Tool | Description |
|---|---|
gitlab_get_file | Read remote file at a ref (e.g. .gitlab-ci.yml) |
gitlab_compare | Diff between two refs |
Local review
| Tool | Description |
|---|---|
gitlab_prepare_review | git worktree + npm ci / composer install |
Prompts (workflows)
| Prompt | Use |
|---|---|
review_merge_request | Full MR review with checklist |
merge_merge_request | Validate mergeability and merge |
fix_failed_ci | Diagnose and fix failed pipeline |
create_mr_from_branch | Create MR from current branch |
triage_open_mrs | Prioritize open MRs |
Resources
| URI | Content |
|---|---|
gitlab://guide | Markdown agent guide (tools and flows) |
gitlab://project/{project_ref} | Project metadata JSON |
Read-only mode
With GITLAB_READ_ONLY=true:
- Allowed: reads (MR, diff, pipeline, merge status, list/get)
- Blocked: merge, comment, inline comment, approve, create/update MR, pipeline control, prepare_review
Useful for analysis/review agents without mutating GitLab.
Migration 0.2 → 0.3
New tools and actions (no breaking changes to existing names):
| Addition | Description |
|---|---|
gitlab_get_mr_merge_status | Mergeability state and blockers |
gitlab_add_mr_inline_comment | Inline diff comment |
gitlab_manage_merge_requests | New actions: merge, close, reopen, mark_draft, mark_ready |
Migration 0.1 → 0.2
Legacy names were renamed with the gitlab_ prefix:
| 0.1.0 | 0.2.0 |
|---|---|
control_pipeline | gitlab_control_pipeline |
get_mr_context | gitlab_get_mr_context |
manage_mrs | gitlab_manage_merge_requests |
prepare_review | gitlab_prepare_review |
gitlab_control_pipeline: retry → retry_job; new actions retry_pipeline and cancel_pipeline.
MCPB install (Claude Desktop / local bundle)
Alternative to npx for clients that support .mcpb files:
- Clone the repo:
git clone ... && npm install && npm run build npm run pack:mcpb— produces.mcpbwithmanifest.json,dist/, andnode_modules- For a smaller bundle:
npm run pack:mcpb:slim - Install the
.mcpbin your client and fill in token + URL
Local development
To contribute or test changes before publishing to npm:
git clone https://github.com/godrix/mcp-gitlab-utils.git
cd mcp-gitlab-utils
npm install
cp .env.example .env # set GITLAB_TOKEN and GITLAB_BASE_URL
npm run dev # tsx, stdio
# or
npm run build && npm startCursor config pointing at the clone (instead of npx):
{
"mcpServers": {
"gitlab-utils": {
"command": "node",
"args": ["/absolute/path/mcp-gitlab-utils/dist/main.js"],
"env": {
"GITLAB_TOKEN": "glpat-...",
"GITLAB_BASE_URL": "https://gitlab.example.com",
"GITLAB_READ_ONLY": "false"
}
}
}
}Extra requirements for local review: npm and/or composer depending on the target repo.
License
MIT