Skip to main content
Glama
@godrix/mcp-gitlab-utils

@godrix/mcp-gitlab-utils

by godrix

@godrix/gitlab-utils-mcp

Install MCP Server

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: gitlab-mcp

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-mcp

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

  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

Available Tools

15 tools
gitlab_add_mr_inline_commentInline MR diff commentA

Creates a review thread on a specific diff line (file + new_line or old_line). Requires write permissions.

Inputs: body (required), file_path (required), new_line, new_path, +5 more.

gitlab_compareCompare branches or commitsA
Read-only

Diff between two refs (branches, tags, or SHAs). Returns commits and file diffs.

Inputs: to (required), from (required), straight, repo_path, +1 more.

gitlab_control_pipelineControl pipeline and jobsC

Lists jobs, plays manual jobs, retries job/pipeline, or cancels pipeline.

Inputs: action (required), job_id, repo_path, project_id, +2 more.

gitlab_get_fileRead repository fileA
Read-only

Returns file content at a ref (branch, tag, or commit SHA). Useful for .gitlab-ci.yml or configs without a local clone.

Inputs: file_path (required), ref, max_chars, repo_path, +1 more.

gitlab_get_job_traceCI job logA
Read-only

Returns the trace (full or truncated log) for a job by job_id.

Inputs: job_id (required), max_chars, repo_path, project_id.

gitlab_get_merge_requestMerge request detailsA
Read-only

Returns MR metadata: title, state, branches, reviewers, labels, head pipeline, approvals, and URL.

Inputs: repo_path, project_id, merge_request_iid.

gitlab_get_mr_contextMR context (diff + pipeline + discussions)A
Read-only

Returns MR changes/diff and optionally failed job traces and review discussions.

Inputs: repo_path, project_id, trace_max_chars, merge_request_iid, +3 more.

gitlab_get_mr_discussionsMerge request discussionsA
Read-only

Lists review threads, inline comments, and general MR notes.

Inputs: per_page, repo_path, project_id, merge_request_iid.

gitlab_get_mr_merge_statusMR merge statusA
Read-only

Summarizes whether the MR can be merged: conflicts, draft, pipeline, approvals, blocking discussions, and actionable blockers.

Inputs: repo_path, project_id, merge_request_iid.

gitlab_get_pipelinePipeline detailsA
Read-only

Returns pipeline state and job list with summary (name, stage, status, duration).

Inputs: repo_path, project_id, pipeline_id, merge_request_iid.

gitlab_list_pipelinesList pipelinesA
Read-only

Lists recent project pipelines, filtering by ref (branch/tag), MR, or status.

Inputs: ref, status, per_page, repo_path, +2 more.

gitlab_manage_merge_requestsManage merge requestsC

List, create, update, approve, merge, close, reopen, draft/ready, or comment on merge requests.

Inputs: action (required), sha, state, title, +14 more.

gitlab_prepare_reviewPrepare review folder (worktree + install)A

Creates a worktree from local repo (repo_path) or shallow HTTPS clone with token. Runs npm ci or composer install by default.

Inputs: repo_path, project_id, install_command, merge_request_iid.

gitlab_resolve_contextResolve local GitLab contextA
Read-only

Discovers project_id, current branch, and merge_request_iid from repo_path. Use before other tools when working in a local clone.

Inputs: repo_path (required).

gitlab_search_projectsSearch GitLab projectsA
Read-only

Lists projects accessible by the token, with optional name or path filter.

Inputs: search, per_page, membership.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose. Even related MR tools (get_merge_request, get_mr_context, get_mr_discussions, get_mr_merge_status) are well-differentiated by their descriptions and scope.

    Naming Consistency5/5

    All tools follow the consistent pattern 'gitlab_verb_noun' in snake_case, with verbs like get, list, add, control, manage, prepare, resolve, search. No mixing of conventions.

    Tool Count5/5

    With 15 tools, the set is well-scoped for a GitLab utilities server covering MR, pipeline, file, and project operations. Neither too sparse nor too overwhelming.

    Completeness4/5

    The tool surface covers core MR and pipeline workflows, file retrieval, comparison, and local repository setup. Minor gaps like lack of explicit pipeline creation or branch listing are acceptable for the domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for the GitLab REST API providing tools to manage projects, merge requests, pipelines, CI/CD variables, approvals, issues, and code reviews.
      6,421 PyPI
      7
      MIT
    • A
      license
      C
      quality
      B
      maintenance
      A production-ready MCP server for GitLab enabling AI assistants to read and manage GitLab projects, merge requests, issues, pipelines, wikis, releases, and more through a unified interface.
      268
      2,012 npm
      10
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI agents to perform automated code reviews on GitLab merge requests, including fetching details, reading diffs, posting inline comments, managing labels, and approving or unapproving MRs.
      2,012 npm
      MIT