@godrix/mcp-gitlab-utils

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 api and read_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/mcp-gitlab-utils"],
      "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/mcp-gitlab-utils

Then use "command": "mcp-gitlab-utils" 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:

1. Clone the repo: git clone ... && npm install && npm run build
2. npm run pack:mcpb — produces .mcpb with manifest.json, dist/, and node_modules
3. For a smaller bundle: npm run pack:mcpb:slim
4. Install the .mcpb in 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 start

Cursor 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