@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)

Related MCP server: mcp-gitlab

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

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

Merge requests

CI/CD

Repository

Local review

Prompts (workflows)

Resources

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):

Migration 0.1 → 0.2

Legacy names were renamed with the gitlab_ prefix:

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