gitlab-mcp
Integrates with a self-hosted GitLab CE 11.3.0 instance through its REST API v4, focused on the merge-request review workflow. Provides tools to list, read, create and update merge requests; inspect per-file diffs with capped patches; read and comment on specific diff lines; reply to and resolve discussion threads; check pipelines and diff versions as the merge gate; and merge requests with a pinned source SHA. Includes read-only helpers for projects, branches, files, labels, users, issues, members, commits and tags, plus a raw API escape hatch.
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., "@gitlab-mcp list open merge requests in group/app and show the diff for !12"
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.
@mohou/gitlab-mcp
An MCP server and a CLI for a self-hosted GitLab CE 11.3.0 instance, built around the merge-request workflow: create, read the diff, comment on a line, reply, resolve, merge.
Two front ends, one core. The CLI has no tool list of its own - its subcommands and flags are derived from the same Zod schemas the MCP tools declare, so the two cannot drift.
Why this exists instead of glab or an existing MCP server
GitLab 11.3.0 was released in September 2018. Every maintained tool has moved on:
Tool | Why it does not work here |
| Officially supports GitLab 16.0+; 15.x and earlier are explicitly unsupported |
GitLab's official MCP server | Requires GitLab 18.3+ ( |
Community GitLab MCP servers | Written against the current API and GraphQL; against 11.3 they 404 or silently misbehave |
The REST API v4 does exist on 11.3 and is complete enough for review work. What it lacks is everything newer, and this client is written against the 11.3 API documentation rather than against today's docs - see What 11.3 does not have.
Related MCP server: mcp-gitlab
Requirements
Node.js 22.6+ (the sources are TypeScript, run directly by Node's type stripping - there is no build step)
A GitLab personal access token with the
apiscope
Install
# as a dependency of something else
npm install @mohou/gitlab-mcp
# the MCP client launches the server through npx, so nothing must be installed first:
npx -y @mohou/gitlab-mcp
# the CLI, without installing anything globally:
npx -y --package @mohou/gitlab-mcp mohou-gitlab toolsThe package ships two binaries: gitlab-mcp (the MCP server, named to match the package so
that npx @mohou/gitlab-mcp finds it) and mohou-gitlab (the CLI).
From a source checkout - there is no build step, Node runs the TypeScript directly:
cd gitlab-mcp
npm install
npm test # 89 offline tests against a mock GitLab 11.3Configure
Variable | Meaning |
| instance root, e.g. |
| personal access token, sent as the |
|
|
| request timeout, default |
| retries for 429/502/503/504, default |
|
|
The token must be treated as a write credential: read_api does not exist before GitLab
12.10, so api is the narrowest scope that can read the API at all. Use a dedicated account,
not a personal one.
Registering the MCP server
Any MCP client works; the server speaks stdio.
{
"mcpServers": {
"gitlab": {
"command": "npx",
"args": ["-y", "@mohou/gitlab-mcp"],
"env": {
"GITLAB_BASE_URL": "http://gitlab.example.com",
"GITLAB_TOKEN": "glpat-xxxxxxxxxxxx"
}
}
}
}From a source checkout, point command at node and args at the absolute path to
bin/gitlab-server.mjs instead.
In this harness (dsh), register it with the mini-app MCP tool instead of editing a file:
mini_app_mcp_add id=gitlab command=node args=["/path/gitlab-mcp/bin/gitlab-server.mjs"] env={GITLAB_BASE_URL:..., GITLAB_TOKEN:...}Two things to know about that path:
${credential:NAME}/${env:NAME}placeholders are resolved for the one-off check but not for the live MCP client until the host restarts. Pass literal values, or register the row and restart once, then verify withmini_app_mcp_list.The harness reaches the host over VPN. If the VPN is down, the first call fails with
network error: fetch failed - is the VPN connected and the host reachable?.
CLI
export GITLAB_BASE_URL=http://gitlab.example.com
export GITLAB_TOKEN=glpat-xxxx
# installed: `mohou-gitlab ...` | without installing: `npx -y --package @mohou/gitlab-mcp mohou-gitlab ...`
node bin/gitlab.mjs tools # every tool, read-only ones marked
node bin/gitlab.mjs describe mr_comment_on_line # purpose and flags
node bin/gitlab.mjs whoami # proves base URL + token
node bin/gitlab.mjs mr_list --project group/app --state opened --per-page 10
node bin/gitlab.mjs mr_changes --project group/app --iid 12 --max-patch-chars 2000
node bin/gitlab.mjs mr_comment_on_line --project group/app --iid 12 \
--path src/app.ts --line 42 --body "this branch is unreachable"
node bin/gitlab.mjs raw_api --method GET --path /projects/group%2Fapp/merge_requestsTool names may be given in full or without the
gitlab_prefix (mr_list=gitlab_mr_list).Flags are dashed and accept the schema spelling too:
--source-branchand--source_branchare the same flag.--no-include-systemsets a boolean false.Output is JSON on stdout, diagnostics on stderr. Exit codes:
0ok,1the call failed,2bad usage.--host,--token,--token-fileoverride the environment for one call (the token is removed fromargv, so it does not appear inps);--dry-runprints the request instead of sending it.
A review, end to end
gitlab_mr_list {project, state:"opened"} # which MR
gitlab_mr_get {project, iid} # state, merge_status, work_in_progress
gitlab_mr_changes {project, iid, maxPatchChars:4000} # files, counts, capped patches
gitlab_mr_discussions {project, iid, onlyUnresolved:true} # what is still open
gitlab_mr_comment_on_line {project, iid, path, line, side, body}
gitlab_mr_reply {project, iid, discussion_id, body}
gitlab_mr_resolve {project, iid, discussion_id}
gitlab_mr_pipelines {project, iid} # the merge gate
gitlab_mr_merge {project, iid, sha} # sha pins the source HEADgitlab_mr_comment_on_line is the tool that earns its keep. GitLab does not accept "file +
line": a diff note needs the merge request's base/start/head SHAs and the old-side line
number. This tool reads the newest diff version, reconstructs the hunk numbering, fills both line
numbers in, and refuses locally when the line is not in the diff - naming the ranges that would
have worked:
cannot place a comment at src/app.ts:99 (new side). src/app.ts: no commentable new-side line 99
(commentable new-side lines: 10-18). Lines that exist in the diff can be commented on;
use gitlab_mr_changes to see the diff.Tools
Core tools (code, src/entities/):
Tool | R/W | Purpose |
| ro | the authenticated user - the cheapest way to prove the token |
| ro | which GitLab version is answering |
| ro | resolve a project path or id |
| ro | label names, and the numeric user ids this API takes |
| ro | branches; one file at a ref, capped |
| ro | find and read merge requests |
| ro | per-file diff summary with capped patches |
| ro | threads, with each diff comment's file and line |
| ro | the merge gate; diff versions (debugging) |
| rw | create and edit, including the draft translation |
| rw | a comment on the merge request itself |
| rw | a diff comment on one line |
| rw | continue a thread; resolve it |
| rw | merge, with the failure modes explained |
| rw | any endpoint - the escape hatch |
Declared extras (tools.d/gitlab-extras.json, read-only, no code): issues, members, project
pipelines, pipeline jobs, commits, tags, group projects. See
tools.d/README.md for the declaration DSL and how to add more.
npm run tools:describe -- <filter> prints the contract as the model sees it, asked of the
server itself over stdio.
What 11.3 does not have
Every entry here is a trap a tool written against current documentation would fall into.
Missing | Consequence here |
Merge request approvals API | There is no approve endpoint on CE 11.3 ( |
| Assignment is the only way to route a merge request; |
| A draft merge request is one whose title starts with |
| Tokens are all-or-nothing write credentials. |
Global code search |
|
Keyset pagination | Offset pagination only; every list tool reports |
| Squash is set on the merge request when it is created or updated, not at merge time. |
| 12.x features. CI config for this instance must use |
| Not used here; user lookup goes through the global |
GraphQL | Experimental at best on 11.0+; this client is REST v4 only. |
Two error messages exist purely because of this table: a 400 mentioning reviewer_ids,
draft or approval rules, and a 401 explaining the scope situation.
Reading the right documentation
Do not read today's API docs when changing this code. Read the version-matched ones from the source tag that produced the instance:
https://gitlab.com/gitlab-org/gitlab-foss/-/raw/v11.3.0/doc/api/merge_requests.md
https://gitlab.com/gitlab-org/gitlab-foss/-/raw/v11.3.0/doc/api/discussions.mdThat is where the parameters in this client were checked, including the detail that a diff
version reports head_commit_sha / base_commit_sha / start_commit_sha while a comment
position wants head_sha / base_sha / start_sha.
Verification
npm test runs against test/mock-gitlab.mjs, which is faithful to the 11.3 shapes (the
*_commit_sha naming, hunk numbering, the 405/406/409 merge failures, nested validation errors)
rather than to GitLab's behaviour. Only a real instance can settle the rest:
GITLAB_BASE_URL=http://gitlab.example.com GITLAB_TOKEN=... \
npm run verify:live -- --project <group/app> --iid <mr> # read-only
GITLAB_BASE_URL=... GITLAB_TOKEN=... \
npm run verify:live -- --project <group/app> --iid <mr> --write # + create/delete a diff noteIt reports PASS/FAIL/SKIP per assumption and exits non-zero on any failure. In --write mode the
only mutation is one probe comment, which it deletes again.
Result against a live GitLab CE 11.3.0 instance (revision 17bd59a): 14 passed, 0 failed,
in both modes. What only that run could establish, and did:
PRIVATE-TOKENauthentication works on 11.3.A project path arrives correctly percent-encoded.
Pagination headers are present and usable (
184merge requests,nextPage=2).GET /versionsnames its SHAsbase_commit_sha/start_commit_sha/head_commit_sha, which is not what a comment position calls them - the mapping the client performs is correct.Real diff text parses, and a real line resolves to a commentable position.
A nested
positionobject is accepted when creating a diff note - the single assumption the offline suite could never test, since it was written from the same reading of the docs.The created note comes back carrying its position, appears in the discussions list, toggles through resolve/unresolve, and deletes cleanly.
A merged merge request still reports
merge_status: can_be_merged, sostateis the field that decides whether a merge is possible. The tool descriptions say so.
Still unverified live, and deliberately listed rather than glossed over:
Area | Why, and how to close it |
The draft positive case ( | Needs a merge request that is actually a draft; the verified project had none among 100. |
| Needs a throwaway branch in a project where creating a merge request is acceptable; 11.3 has no API to delete a merge request, so the residue is one closed or merged one. |
Everything else in this file that is not one of those two lines has been exercised against the real instance.
Extending
A new endpoint with no logic - add a declaration to
tools.d/*.json. No code, no restart of anything but the server.A new endpoint with logic, or a non-JSON response - add a tool in
src/entities/. Text endpoints (job traces, raw files) cannot be expressed in the JSON layer, because that layer parses every response as JSON.Both front ends pick it up automatically: the MCP tool and the CLI subcommand appear together.
Layout: src/gitlab.ts (transport, pagination, error translation) - src/diff.ts (unified diff →
position) - src/entities/ (tools) - src/jsonTools.ts (the declaration DSL) - src/cli.ts +
src/args.ts (CLI) - src/index.ts (MCP server).
Maintainer: publishing
Prerequisites, in order:
Node 22.6+ locally, and
npm testgreen (prepublishOnlyenforces it).npm login(orNPM_TOKENin the environment) for the account that may publish.The
@mohouscope must exist and you must be able to publish to it. A scoped name is not optional: npm rejectsmohou/gitlab-mcp, so the package is@mohou/gitlab-mcp. If@mohouis not yet an npm organization, create it on npmjs.com and add yourself as an owner - or, for an internal registry, map the scope instead:# .npmrc (safe to commit - no token in it) @mohou:registry=https://your-internal-registry/That
.npmrcalso decides wherenpm publishgoes, so set it before publishing.publishConfig.access = "public"is already set inpackage.json; without it a scoped package publishes as restricted and fails on a free plan.
Then:
npm test # 93 offline tests
npm run pack:check # the file list that would ship - verify dist/ and tools.d/ are in it
npm run verify:package # pack, install into a temp dir, run both binaries, speak MCP to them
npm publish --dry-run # the whole publish path, including prepublishOnly, without publishing
npm version patch # or minor/major; updates package.json + git tag
npm publish # prepublishOnly runs both gates aboveDevelopment needs no build; the published package does
This is the one place where the package departs from a plain "run the TypeScript" layout, and the reason is a hard Node restriction:
ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPINGNode strips types for the application's own sources but refuses to do so for anything under
node_modules. So src/*.ts runs fine in a checkout (and every test relies on that) and cannot
run at all once installed as a dependency. The package therefore ships dist/*.js, built by
scripts/build.mjs (esbuild, dependencies kept external).
The bin entries resolve the entry source first, bundle second:
bin/gitlab-server.mjs -> src/index.ts if it exists, else dist/index.js
bin/gitlab.mjs -> src/cli.ts if it exists, else dist/cli.jsSources first, not bundle first, and the order is not cosmetic: preferring dist/ means that
after any build a checkout silently runs the stale bundle, which once hid a real bug in the
sibling jira-mcp project during exactly this kind of verification. The published tarball
contains no src/ at all, so an install takes the bundle path; npm run verify:package fails if
src/ ever appears in the tarball, because shipping it would send an install down the source path
into ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING.
prepack runs the build, so npm pack and npm publish always emit a fresh bundle; dist/ is
gitignored. Editing a tool means editing the TypeScript, and nothing else - tests run the sources
and publishing rebuilds.
Other notes specific to this package:
tools.d/must ship. The server loadstools.d/*.jsonfrom the package root at startup; if that directory were dropped fromfiles, every JSON-declared tool would disappear and startup would fail. Bothpack:checkandverify:packagecheck for it.enginesrequires Node 22.6+ because the fallback path and the test suite use type stripping. The bundle itself would run on older Node.No provenance attestation.
npm publish --provenanceneeds a public source repository on a supported CI provider; this repository is self-hosted, so provenance is not available.Run
npm publish --dry-runbefore the real one. npm exports its configuration to lifecycle scripts, so a dry run reachesprepublishOnlywithnpm_config_dry_run=true- which once madeverify:packagefail, becausenpm packprints a filename without writing the file and the install that follows hits ENOENT. The script neutralises that variable; the dry run is the check that it stays neutralised.prepublishOnlyruns the offline suite and the package verification only. The live checks (npm run verify:live) need VPN access and a token, so they are not part of publishing.
Available Tools
30 toolsgitlab_branches_listARead-only
List a project's branches. Useful before gitlab_mr_create to confirm the source branch exists and to find the target branch.
Inputs: project (required), page, search, perPage. Returns: items, pagination
gitlab_commit_listARead-only
List repository commits on a ref. Use it to see what a merge request's source branch contains beyond the diff.
Inputs: project (required), ref, page, perPage. Returns: items, pagination
gitlab_file_getARead-only
Read one file from the repository at a ref. Defaults to the project default branch - pass ref= to read the file as the merge request sees it. Output is capped, and a truncated read says so.
Inputs: path (required), project (required), ref, maxChars. Returns: repository file content
gitlab_group_projectsBRead-only
List the projects of a group (including its subgroups), to find a project path from a group.
Inputs: group (required), page, search, perPage. Returns: items, pagination
gitlab_issue_getARead-only
Get one issue by its project-scoped iid.
Inputs: iid (required), project (required). Returns: object
gitlab_labels_listARead-only
List a project's labels. Check here before setting labels: 11.3 creates an unknown label silently when the account may, and rejects it when the account may not.
Inputs: project (required), page, search, perPage. Returns: items, pagination
gitlab_mr_changesARead-only
The merge request diff, summarised per file: status, added/removed line counts and a capped patch. Read this before commenting on a line, and to learn which paths and lines exist. Use path to pull one file's patch at a larger cap.
Inputs: iid (required), project (required), path, maxFiles, +1 more. Returns: summarised merge request diff
gitlab_mr_commentA
Post a comment on the merge request itself. For a comment on a specific line of the diff, use gitlab_mr_comment_on_line so it appears in the changed line's thread.
Inputs: iid (required), body (required), project (required). Returns: a note (comment) inside a discussion
gitlab_mr_comment_on_lineA
Comment on one line of the merge request diff, as a normal review comment. Give the path exactly as gitlab_mr_changes reports it and the line number in that side of the file. The required base/start/head SHAs and the old-side line number are resolved from the merge request's latest diff version, so a stale SHA or a line that is not in the diff is reported instead of being sent. The result carries discussion_id - pass it to gitlab_mr_reply to continue the thread.
Inputs: iid (required), body (required), line (required), path (required), +2 more. Returns: result of creating or replying to a diff comment
gitlab_mr_createA
Create a merge request from source_branch into target_branch. On 11.3 there is no reviewers attribute (assign instead) and no draft parameter: pass draft:true and the required "WIP: " title prefix is applied for you. Creating an MR whose branches already have an open one fails with 409 - update that one instead.
Inputs: title (required), project (required), source_branch (required), target_branch (required), +7 more. Returns: merge request
gitlab_mr_discussionsARead-only
List the discussion threads of a merge request, with each diff comment's file and line. System notes are filtered out by default and resolved is derived from the thread's notes, so the returned page can be shorter than pagination.total (which is GitLab's raw count).
Inputs: iid (required), project (required), page, perPage, +3 more. Returns: items, pagination
gitlab_mr_getARead-only
Get one merge request. Read state before anything else: only an opened merge request can be merged, and a merged one still reports merge_status can_be_merged. work_in_progress says whether it is a draft.
Inputs: iid (required), project (required). Returns: merge request
gitlab_mr_listARead-only
List a project's merge requests. Defaults to state=opened because the raw API would return every state at once. This version has no reviewers or draft filter - read work_in_progress on each item instead.
Inputs: project (required), page, sort, scope, +10 more. Returns: items, pagination
gitlab_mr_mergeA
Merge a merge request. The merge request must be opened - merging a merged or closed one fails. It fails with 405 while it is not mergeable (conflicts, or a required pipeline still running) and with 409 when the source branch moved since you read it, so read the merge request first and pass its sha to pin the merge.
Inputs: iid (required), project (required), sha, merge_commit_message, +2 more. Returns: merge request
gitlab_mr_pipelinesARead-only
List the pipelines recorded against this merge request. Read before merging: 11.3 refuses the merge while one is running or failed.
Inputs: iid (required), project (required), page, perPage. Returns: items, pagination
gitlab_mr_replyA
Reply inside an existing discussion thread. Use it to answer a review comment instead of starting a second thread on the same line.
Inputs: iid (required), body (required), project (required), discussion_id (required). Returns: result of creating or replying to a diff comment
gitlab_mr_resolveA
Resolve or unresolve a discussion thread. This is how review state is recorded on CE 11.3, which has no approve API. Reply to the thread first if the resolution needs an explanation.
Inputs: iid (required), project (required), discussion_id (required), resolved. Returns: merge request discussion thread
gitlab_mr_updateA
Update a merge request. Pass draft to set or clear the "WIP: " prefix (when no title is given the current title is read first). labels:[] clears all labels and assignee_id:0 unassigns - omitting a field leaves it alone.
Inputs: iid (required), project (required), draft, title, +9 more. Returns: merge request
gitlab_mr_versionsARead-only
List the diff versions of a merge request, newest first as GitLab returns them. Only needed to debug comment positions - gitlab_mr_comment_on_line resolves them itself.
Inputs: iid (required), project (required), page, perPage. Returns: items, pagination
gitlab_pipeline_jobsARead-only
List the jobs of a pipeline with their status, stage and failure reason. Job logs are text, not JSON, so they are not reachable from this JSON layer.
Inputs: project (required), pipelineId (required), page, perPage. Returns: items, pagination
gitlab_project_getARead-only
Get a project by id or path. Use it to turn a project name into the path the other tools take, and to read default_branch.
Inputs: project (required). Returns: GitLab project
gitlab_project_issuesCRead-only
List a project's issues. Read-only extra: this file declares the endpoints the merge-request tools do not cover, so they cost no code.
Inputs: project (required), page, state, labels, +2 more. Returns: items, pagination
gitlab_project_membersARead-only
List a project's members with their access level and numeric user id - the ids gitlab_mr_create/update take as assignee_id.
Inputs: project (required), page, search, perPage. Returns: items, pagination
gitlab_project_pipelinesARead-only
List a project's pipelines, optionally filtered by ref or status. On 11.3 a merge request's own pipelines come from gitlab_mr_pipelines.
Inputs: project (required), ref, page, status, +1 more. Returns: items, pagination
gitlab_project_searchARead-only
Search projects visible to this token by name. Use it when the exact project path is unknown.
Inputs: search (required), page, perPage. Returns: items, pagination
gitlab_raw_apiA
Call any API v4 endpoint directly - the escape hatch for endpoints with no dedicated tool (issues, labels, pipelines, snippets, members). Prefer a dedicated tool when one exists: this one does no validation, so a wrong path or field is exactly what the instance receives.
Inputs: path (required), method (required), body, query. Returns: raw API result
gitlab_server_versionARead-only
Get the GitLab version answering this token (GET /version). Confirms which version the instance is on, which matters because most public documentation describes newer releases.
Inputs: no named parameters. Returns: object
gitlab_tags_listCRead-only
List repository tags.
Inputs: project (required), page, perPage. Returns: items, pagination
gitlab_users_searchARead-only
Find users by name or username. Needed because 11.3 assigns and filters by numeric user id and never by username.
Inputs: search (required), page, perPage. Returns: items, pagination
gitlab_whoamiARead-only
Get the authenticated user. Call this first: it is the cheapest way to prove the token and base URL work before any write.
Inputs: no named parameters. Returns: user reference
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 30 tools
Most tools target distinct resources and actions, but the comment-related trio (gitlab_mr_comment, gitlab_mr_comment_on_line, gitlab_mr_reply) and the pipeline listings (gitlab_mr_pipelines, gitlab_project_pipelines, gitlab_pipeline_jobs) require careful reading to avoid misselection. Descriptions do a good job of clarifying boundaries, so confusion is limited but not absent.
All names use snake_case with a uniform gitlab_ prefix, and most follow a resource_action pattern. Minor deviations exist: some list tools include an explicit verb (gitlab_labels_list, gitlab_branches_list), while others omit it (gitlab_project_issues, gitlab_project_members, gitlab_mr_discussions), and a few names are phrase-like (gitlab_whoami, gitlab_raw_api).
30 tools is heavy for a server whose primary focus is merge request workflows. Many auxiliary read-only list/get tools (e.g., project issues, members, pipelines, commits, tags, group projects) add bulk that could be consolidated or handled via the provided raw API escape hatch.
The core merge request lifecycle — list, get, changes, create, update, comment, line comment, reply, resolve, discussions, versions, pipelines, and merge — is well-covered. Gaps remain for common write operations outside MRs (issue creation/update, branch creation, file/commit writes), though the raw API tool provides a workaround.
Maintenance
Related MCP Connectors
Unofficial GitLab MCP — wraps the GitLab REST API v4 (BYO API key)
GitLab Public MCP — wraps the GitLab REST API v4 (public endpoints, no auth)
Go MCP server for GitLab: 2 dynamic tools reach 1000+ REST/GraphQL actions. Free/CE, no paid tier.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceMCP server for interacting with GitLab API, supporting both self-hosted instances and gitlab.com. Provides tools for managing issues, merge requests, code review, pipelines, milestones, releases, search, and file access.MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for the GitLab REST API providing tools to manage projects, merge requests, pipelines, CI/CD variables, approvals, issues, and code reviews.3,759 PyPI7MIT
- FlicenseBqualityDmaintenanceProvides tools to interact with a self-hosted GitLab instance, enabling project, issue, note, search, todo, and wiki page management through MCP.161-
- FlicenseNot gradedqualityDmaintenanceMCP server for managing GitLab repositories — merge requests, pipelines, branches, and file operations.1-