@godrix/mcp-gitlab-utils
This MCP server provides a GitLab REST API interface for AI agents, enabling management of merge requests, CI/CD pipelines, repositories, and local code review workflows.
Discovery
Resolve
project_id, current branch, and MR IID from a local repository path (gitlab_resolve_context).Search for accessible GitLab projects by name or path (
gitlab_search_projects).
Merge Requests
Get MR metadata — title, state, branches, reviewers, labels, pipeline, approvals, and URL (
gitlab_get_merge_request).Check mergeability, including conflicts, draft status, pipeline results, approvals, and blocking discussions (
gitlab_get_mr_merge_status).Fetch MR diff/changes, optionally with failed CI job logs and discussions (
gitlab_get_mr_context).List review threads, inline comments, and general notes (
gitlab_get_mr_discussions).Post inline review comments on specific diff lines (
gitlab_add_mr_inline_comment).Full MR lifecycle: list, get, create, update, approve/unapprove, comment, merge, close, reopen, mark as draft/ready (
gitlab_manage_merge_requests).
CI/CD Pipelines
List recent pipelines filtered by branch, MR, or status (
gitlab_list_pipelines).Get pipeline details and job summaries (
gitlab_get_pipeline).Fetch full or truncated logs for a specific CI job (
gitlab_get_job_trace).Control pipelines/jobs: list jobs, play manual jobs, retry a job or pipeline, cancel a pipeline (
gitlab_control_pipeline).
Repository
Read remote file contents at any branch, tag, or commit SHA (
gitlab_get_file).Compare two refs to get commits and file diffs (
gitlab_compare).
Local Review
Create a
git worktreefrom a local repo or shallow clone and auto-run dependency installation (e.g.,npm ci,composer install) for local code review (gitlab_prepare_review).
Read-Only Mode
Set
GITLAB_READ_ONLY=trueto block all write operations (merge, comment, approve, pipeline control, prepare_review), safe for analysis-only agents.
Built-in Prompts/Workflows Predefined workflows for common tasks: reviewing an MR, merging an MR, diagnosing/fixing failed CI, creating an MR from a branch, and triaging open MRs.
Provides tools for interacting with GitLab's API, enabling AI agents to manage merge requests, pipelines, repositories, and perform code reviews.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@godrix/mcp-gitlab-utils check the merge status of MR #42"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@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)
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-mcpThen use "command": "gitlab-utils-mcp" in mcp.json (no npx).
Environment variables
Variable | Required | Description |
| Yes | Sent as |
| Yes | e.g. |
| No | Fallback |
| No | Default: |
| No | Default: |
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 |
| Resolve |
| Search projects accessible by the token |
Merge requests
Tool | Description |
| MR metadata (state, reviewers, pipeline) |
| Mergeability: conflicts, draft, pipeline, approvals, blockers |
| Diff/changes + optional CI traces and discussions |
| Review threads and comments |
| Inline comment on a diff line |
|
|
CI/CD
Tool | Description |
| List pipelines (by ref, MR, or status) |
| Pipeline + jobs |
| Job log |
|
|
Repository
Tool | Description |
| Read remote file at a ref (e.g. |
| Diff between two refs |
Local review
Tool | Description |
|
|
Prompts (workflows)
Prompt | Use |
| Full MR review with checklist |
| Validate mergeability and merge |
| Diagnose and fix failed pipeline |
| Create MR from current branch |
| Prioritize open MRs |
Resources
URI | Content |
| Markdown agent guide (tools and flows) |
| 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 |
| Mergeability state and blockers |
| Inline diff comment |
| New actions: |
Migration 0.1 → 0.2
Legacy names were renamed with the gitlab_ prefix:
0.1.0 | 0.2.0 |
|
|
|
|
|
|
|
|
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 buildnpm run pack:mcpb— produces.mcpbwithmanifest.json,dist/, andnode_modulesFor a smaller bundle:
npm run pack:mcpb:slimInstall 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
Available Tools
15 toolsgitlab_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 commitsARead-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 fileARead-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 logARead-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 detailsARead-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)ARead-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 discussionsARead-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 statusARead-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 detailsARead-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 pipelinesARead-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 contextARead-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 projectsARead-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
Scored across 15 tools
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.
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.
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.
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
Related MCP Connectors
Unofficial GitLab MCP — wraps the GitLab REST API v4 (BYO API key)
Go MCP server for GitLab: 2 dynamic tools reach 1000+ REST/GraphQL actions. Free/CE, no paid tier.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceMCP server for the GitLab REST API providing tools to manage projects, merge requests, pipelines, CI/CD variables, approvals, issues, and code reviews.6,421 PyPI7MIT
- AlicenseCqualityBmaintenanceA 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.2682,012 npm10MIT
- AlicenseNot gradedqualityDmaintenanceAn 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 npmMIT
- FlicenseAqualityDmaintenanceMCP server for GitLab that enables AI assistants to manage CI pipelines, job logs, repositories, branches, merge requests, and commits via the GitLab REST API.20-