GitLab MCP
The GitLab MCP server exposes 85+ tools for comprehensive interaction with GitLab (gitlab.com or self-hosted) via its REST API v4. It supports read‑only mode, single‑project locking, and fine‑grained access control through scopes and tokens for secure, controlled operations.
Instance & User: Verify connection (
gitlab_whoami), search across GitLab, manage todos, list events, look up users, and render markdown.Projects & Groups: List, get, create, update, delete, fork projects; manage members; list groups and their resources; view project statistics.
Issues: Full CRUD; manage comments, threaded discussions, time tracking, labels, milestones, boards, issue links, and emoji reactions.
Merge Requests: Full CRUD, merge, approve/unapprove, rebase; view per‑file diffs, comment on code lines, resolve threads, and inspect approvals/commits/pipelines.
Repository: Browse and read files (including images), commit single or multiple files, manage branches/commits/tags/releases, view blame, compare refs, and check branch protection rules.
CI/CD: List/trigger/retry/cancel pipelines and jobs; download logs (tailed for quick failure diagnosis) and artifacts (e.g., test screenshots); manage CI variables; validate
.gitlab-ci.yml; view environments, deployments, and schedules.Attachments & Screenshots: Download authenticated attachments (images returned as viewable), list all attachments of an issue/MR/epic, upload local files to get markdown embed snippets, and make authenticated GET requests to any instance URL.
Security: Read‑only mode, restrict to a single project, and enforce access via scoped tokens.
General API: Call any GitLab REST API v4 endpoint directly as an escape hatch.
Other: Manage wikis, snippets, webhooks; list packages and container registry repositories/tags.
Provides tools for interacting with GitLab, enabling management of issues, merge requests, repository files, CI/CD pipelines, wikis, packages and registries, plus a generic API endpoint. Supports both gitlab.com and self-hosted instances.
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 show me the latest pipeline status for the main branch"
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.
GitLab MCP
An MCP server for GitLab — works with gitlab.com and with any self-hosted instance
(https://gitlab.velocorner.ch, https://dev.tectiers.com, anything else).
85 tools covering issues, merge requests, the repository, CI/CD, wiki, packages and
registries, plus gitlab_api_request — a generic escape hatch to any REST API v4 endpoint
that has no dedicated tool.
The headline feature: the server reads attachments. A screenshot pasted into an issue is downloaded with authentication and handed to the model as an image — not as a link it cannot open.
Two ways to run it
Mode | Transport | Configuration comes from | Use it when |
Hosted | Streamable HTTP on | request headers, per call | clients should connect to a URL with nothing installed |
Local | stdio | environment variables | the instance is private, or credentials must not leave the machine |
The public deployment lives at https://gitlab-mcp.webapace.ink — the landing page on /,
the MCP endpoint on /mcp. Connecting to it needs no install:
claude mcp add --transport http gitlab \
https://gitlab-mcp.webapace.ink/mcp \
--header "X-GitLab-Url: https://gitlab.example.com" \
--header "X-GitLab-Token: glpat-xxxxxxxxxxxx"Or write the configuration yourself. The same object goes into .mcp.json in a repository,
~/.claude.json, claude_desktop_config.json or .cursor/mcp.json — fill in the blanks:
{
"mcpServers": {
"gitlab": {
"type": "http",
"url": "https://gitlab-mcp.webapace.ink/mcp",
"headers": {
"X-GitLab-Url": "",
"X-GitLab-Token": "",
"X-GitLab-Project-Id": ""
}
}
}
}Header | Fill in with | If left empty |
| the address as typed in the browser, |
|
| the | the request is refused — this one is required |
| default project: | tools ask for a project each time |
X-GitLab-Project-Lock and X-GitLab-Read-Only can be added the same way; see
Hosted mode for the full header list.
Keep the file out of version control, or write "X-GitLab-Token": "${GITLAB_TOKEN}" — Claude Code
and Cursor substitute environment variables, so the secret stays in your shell.
Two things worth knowing when a change appears to do nothing:
In Claude Code an entry added to the local scope (kept in
~/.claude.json) takes precedence over the project's.mcp.json.claude mcp listshows what is actually in use, andclaude mcp remove <name> -s localdrops a stale one.Client configuration is read at startup, so restart the app after editing the file.
The rest of this document is for running your own copy in either mode.
Related MCP server: gitlab-mcp
Install
git clone <repo> gitlab-mcp
cd gitlab-mcp
npm install
npm run buildRequires Node.js 20 or newer.
Token
GitLab → Settings → Access Tokens. A personal, group or project access token all work.
Scope | What it allows |
| everything read-only: issues, MRs, files, pipelines, attachments |
| the above plus writes: comments, commits, merge requests, issue edits |
A project access token is the safest choice when the work is confined to one project.
Configuration
In stdio mode everything is configured through environment variables.
Variable | Required | Default | Description |
| yes |
| Instance URL. A trailing |
| yes | — | Access token |
| no | — | Default project: |
| no |
|
|
| no |
|
|
| no |
|
|
| no |
|
|
| no |
| Per-request timeout |
| no |
| Size cap for downloaded attachments |
Aliases that are also read: GITLAB_API_URL / CI_SERVER_URL for the URL,
GITLAB_PERSONAL_ACCESS_TOKEN / GITLAB_ACCESS_TOKEN for the token.
Connecting from Claude Code
claude mcp add gitlab \
--env GITLAB_URL=https://gitlab.velocorner.ch \
--env GITLAB_TOKEN=glpat-xxxxxxxxxxxx \
-- node /absolute/path/gitlab-mcp/dist/index.jsOr drop a .mcp.json into the root of your working repository, so the configuration travels
with the project:
{
"mcpServers": {
"gitlab": {
"command": "node",
"args": ["/absolute/path/gitlab-mcp/dist/index.js"],
"env": {
"GITLAB_URL": "https://dev.tectiers.com",
"GITLAB_TOKEN": "glpat-xxxxxxxxxxxx",
"GITLAB_PROJECT_ID": "team/backend",
"GITLAB_PROJECT_LOCK": "true"
}
}
}
}The same block works in Claude Desktop (claude_desktop_config.json) and Cursor (.cursor/mcp.json).
Several instances at once — just several entries with different names:
{
"mcpServers": {
"gitlab-com": { "command": "node", "args": ["…/dist/index.js"], "env": { "GITLAB_URL": "https://gitlab.com", "GITLAB_TOKEN": "glpat-…" } },
"gitlab-work": { "command": "node", "args": ["…/dist/index.js"], "env": { "GITLAB_URL": "https://gitlab.velocorner.ch", "GITLAB_TOKEN": "glpat-…" } }
}
}To verify the connection, ask for gitlab_whoami — it returns the authenticated user, the
instance URL and the GitLab version.
Hosted mode
Start the HTTP transport with MCP_TRANSPORT=http (or --http). It serves:
Route | Purpose |
| the landing page ( |
| the MCP endpoint, stateless — one server instance per request |
| liveness probe |
| generated per request from the |
| static files from |
GET /index.html redirects to / so the page has a single canonical address.
Every request carries its own credentials, so one deployment serves many users and many instances without holding state:
Header | Maps to | Notes |
|
| required unless the deployment sets a default |
|
|
|
|
| default project |
|
|
|
|
|
|
|
|
|
TLS verification, timeouts and the attachment size cap are deliberately not header-controlled: they are process-wide and belong to whoever runs the deployment.
Deployment settings:
Variable | Default | Description |
|
|
|
|
| listen address |
|
| page served at |
|
| directory holding the icons, the manifest and the preview image |
| — | comma-separated hostnames; when set, only these instances may be targeted |
| — | fallbacks used when the corresponding header is absent |
Without an allowlist the server refuses private addresses (localhost, RFC 1918 ranges,
169.254.*, *.internal, *.local) so a public deployment cannot be used to probe the network
it runs in. A GitLab on a private network therefore needs a local or internal deployment — which
is the correct answer anyway.
docker build -t gitlab-mcp .
docker run -p 8080:8080 -e GITLAB_ALLOWED_INSTANCES=gitlab.example.com gitlab-mcpDeploying
deploy.sh does the whole cycle on the server — pull, build, swap the container, verify,
purge the CDN cache:
./deploy.sh # the usual deploy
./deploy.sh --page-only # only replace landing.html in the running container, no rebuild
./deploy.sh --no-pull # deploy the working tree as it is
./deploy.sh --logs # follow the container log afterwardsCopy deploy.env.example to deploy.env on the server and set the port, container name,
PUBLIC_URL and, if the site sits behind Cloudflare, a zone id and an API token with the
Cache Purge permission. deploy.env is git-ignored, so server-specific values stay there.
The previous image is tagged :previous before every build, and a failed health check
restores it automatically and exits non-zero, so a broken build never stays deployed.
Because the server reads landing.html from disk on every request, --page-only publishes
a page change in a second without rebuilding anything — but the file is baked into the image
by COPY landing.html, so the next full deploy is what makes it permanent.
Landing page assets
assets/ holds everything the page references: favicon.svg (the source of every raster icon),
favicon.ico, the touch and PWA icons, site.webmanifest, and og-image.png — the 1200×630
preview used by link unfurlers, rendered from assets/og-card.html.
The PNG and ICO files are committed, so a normal build needs nothing extra. Regenerate them only
after editing favicon.svg or og-card.html:
npm run assets # headless Chrome does the rasterising; set CHROME=… if it is not foundThe page carries a description, canonical URL, Open Graph and Twitter cards, and JSON-LD
(SoftwareApplication, WebSite, FAQPage). Those absolute URLs point at
gitlab-mcp.webapace.ink; a self-hosted copy that should be indexed under its own name needs
them replaced in landing.html — robots.txt and sitemap.xml already follow the request host
on their own.
Because the endpoint accepts tokens from callers, put it behind TLS and treat access logs accordingly. The server itself keeps nothing: no sessions, no storage, one throwaway server instance per request.
Single-project isolation
Two modes, and they stack.
Soft — a default project. Only GITLAB_PROJECT_ID is set: the project_id argument becomes
optional, but any other project is still reachable.
Hard — GITLAB_PROJECT_LOCK=true. The server resolves the project at startup and from then on:
any
project_idother than the configured one is refused — the id, the full path and the URL-encoded path are all compared, so42,group/projectandgroup%2Fprojectcount as the same project;group-wide and instance-wide operations (listing groups, group members, group search) are refused;
gitlab_api_requestonly accepts paths under/projects/<your project>/plus the harmless/user,/version,/markdown,/todos;gitlab_download_urlandgitlab_read_attachmentonly fetch URLs that belong to the project;gitlab_list_projectsreturns exactly one project and an unscopedgitlab_searchsearches inside it.
GITLAB_PROJECT_LOCK=true + GITLAB_READ_ONLY=true + a project access token with read_api
gives a server that can neither reach outside the project nor change anything inside it.
Screenshots and attachments
This is the part worth its own section. GitLab stores attachments at URLs like
/uploads/<hash>/screenshot.png — unreachable without authentication, and written into the issue
body as a relative link.
How it works:
1. Fetch the issue. gitlab_get_issue returns the description, every comment, and a separate
attachments block with absolute URLs already resolved:
{
"attachments": [
{
"title": "Screenshot_2026-08-04",
"url": "https://gitlab.velocorner.ch/team/web/uploads/a1b2…/Screenshot.png",
"is_image_embed": true,
"source": "description"
},
{ "title": "log", "url": "https://…/uploads/c3d4…/error.log", "is_image_embed": false, "source": "note #98123" }
]
}2. Look at the image. gitlab_read_attachment with that url — PNG/JPEG/GIF/WebP come back as
an image the model can actually see. Text files come back as text, anything else as a base64 resource.
Relative paths work too: {"url": "/uploads/a1b2…/Screenshot.png", "project_id": "team/web"}.
Related tools:
gitlab_list_attachments— scan an issue/MR/epic and get only the attachment list, without the body;gitlab_get_filewithas_image: true— view an image committed to the repository;gitlab_get_job_artifact— pull a screenshot out of CI artifacts (Playwright, Cypress);gitlab_download_url— authenticated GET of any URL on the instance;gitlab_upload_file— upload a local file and get the markdown snippet to embed in a comment.
Downloads try several routes in order: the API first (/projects/:id/uploads/:secret/:file,
GitLab 16.6+), then the web URL with a PRIVATE-TOKEN header, then with ?private_token=. A
response that turns out to be a login page counts as a failure and the next route is tried — which
is what makes this work on older self-hosted instances.
Tools
Identifiers: a project is a numeric id or a full path group/subgroup/project; issues and merge
requests are addressed by their iid (the number shown in the UI), not the global id.
Every list tool shares the arguments page, per_page (max 100), all_pages (walk the whole
pagination) and limit.
Instance and utility
Tool | Description |
| Current user, instance URL, GitLab version — the configuration smoke test |
| Search across projects, issues, MRs, code, commits, wiki, comments |
| The user's todo list and marking items done |
| Activity stream of the current user or a project |
| User lookup (project members only in locked mode) |
| Render markdown through GitLab (expands relative links) |
| Any REST API v4 endpoint: epics, feature flags, admin, instance specifics |
Projects and groups
Tool | Description |
| Project list and details |
| Project management |
| Project members |
| Groups |
| Languages, contributors, repository size |
Issues
Tool | Description |
| Issues of a project, a group or the whole instance, with filters |
| The whole issue: body, comments, attachments |
| Issue CRUD, including close/reopen |
| Comments on issues, MRs, snippets, epics, commits |
| Discussion threads |
| Links between issues (relates to / blocks / blocked by) |
| Estimate and spent time |
| Merge requests connected to the issue |
| Labels, milestones, boards |
| Emoji reactions |
Merge requests
Tool | Description |
| MR list and details (with attachments) |
| Per-file diff, truncated to a readable size |
| MR lifecycle |
| approve, unapprove, rebase, cancel auto-merge, commits, participants, pipelines |
| Comment on a specific line of a file under review |
| Resolve or unresolve a thread |
Repository
Tool | Description |
| File tree and contents ( |
| Write one file, or commit several operations at once |
| Branches: create, delete, prune merged |
| History, commit diff, ref comparison, blame |
| Tags and releases |
| Branch protection rules |
CI/CD
Tool | Description |
| Pipelines: inspect, run, retry, cancel |
| Jobs: retry, cancel, play, erase |
| Log of a failed job (tail by default) |
| Job artifact; images come back as images |
| CI/CD variables |
| Validate |
| Environments, deployments, schedules |
Attachments
Tool | Description |
| Download an attachment with authentication; images arrive as images |
| Every attachment of an issue/MR/epic in one list |
| Upload a local file, get the markdown snippet back |
| Authenticated GET of any instance URL |
Everything else
Tool | Description |
| Wiki pages: read and edit |
| Project snippets |
| Webhooks |
| Package registry and container registry |
When no tool fits
gitlab_api_request calls any REST API v4
endpoint:
{
"method": "GET",
"path": "/groups/42/epics",
"query": { "state": "opened" },
"all_pages": true
}Slashes inside identifiers are encoded as %2F: /projects/group%2Fproject/issues.
In read-only mode only GET passes; in locked mode only paths inside the locked project do.
Development
npm run build # compile
npm run dev # tsc --watch
npm run typecheck # types only
npm run start # stdio mode
npm run start:http # hosted mode on PORT (default 8080)Layout:
src/
index.ts entry point, picks stdio or HTTP
server.ts builds a configured MCP server with every tool registered
http.ts hosted mode: landing page, stateless /mcp, per-request credentials
config.ts configuration from environment or headers
gitlab-client.ts HTTP client: pagination, errors, downloads, project lock
tools/
helpers.ts shared argument schemas, result formatting, guards
core.ts instance, search, todos, raw API
projects.ts projects and groups
issues.ts issues, comments, labels, milestones
merge-requests.ts merge requests, diffs, reviews
repository.ts files, branches, commits, tags, releases
ci.ts pipelines, jobs, artifacts, variables
attachments.ts attachments and screenshots
misc.ts wiki, snippets, hooks, registriesTo add a tool, call defineTool in the appropriate module: error handling, the read-only guard
and the project lock are wired in automatically.
Troubleshooting
Symptom | Cause |
| The token expired, was revoked, or belongs to a different instance |
| Missing scope ( |
| Wrong project id/path, or the token cannot see it. The path must be complete: |
Attachment will not download | Check that the URL belongs to the same instance; for a private CA set |
| Raise |
Server will not start | Logs go to stderr with the |
A visual walkthrough with examples lives in landing.html at the repository root.
Available Tools
85 toolsgitlab_add_project_memberAdd project memberC
Grants a user access to a project.
Inputs: user_id (required), access_level (required), expires_at, project_id.
gitlab_api_requestRaw GitLab API requestBRead-only
Escape hatch that calls ANY GitLab REST API v4 endpoint with the configured credentials. Use it for endpoints without a dedicated tool (epics, packages, feature flags, admin, custom instance routes). See https://docs.gitlab.com/ee/api/api_resources.html
Inputs: path (required), method (required), body, limit, +2 more.
gitlab_award_emojiEmoji reactionsC
Lists, adds or removes emoji reactions.
Inputs: iid (required), action (required), target_type (required), name, +3 more.
gitlab_blame_fileBlame fileCRead-only
Per-line authorship for a file.
Inputs: ref (required), file_path (required), range_end, project_id, +1 more.
gitlab_branch_actionBranch actionsBDestructive
Gets, creates or deletes branches.
Inputs: action (required), ref, branch, project_id.
gitlab_ci_variablesCI/CD variablesBDestructive
Manages project CI/CD variables. Values of masked variables are not returned by GitLab.
Inputs: action (required), key, value, masked, +4 more.
gitlab_commit_filesCommit multiple filesB
Creates one commit that touches several files at once (create/update/delete/move).
Inputs: branch (required), actions (required), commit_message (required), project_id, +1 more.
gitlab_compareCompare refsARead-only
Diff between two branches, tags or commits, including the commit list.
Inputs: to (required), from (required), straight, project_id.
gitlab_create_issueCreate issueC
Creates an issue in a project.
Inputs: title (required), labels, epic_id, due_date, +6 more.
gitlab_create_labelCreate labelC
Creates a project label.
Inputs: name (required), color (required), project_id, description.
gitlab_create_merge_requestCreate merge requestC
Opens a merge request between two branches.
Inputs: title (required), source_branch (required), target_branch (required), labels, +8 more.
gitlab_create_merge_request_threadComment on MR codeA
Starts a review thread. With file_path + line + diff_refs it anchors to a specific line; without them it posts a general discussion. Get diff_refs from gitlab_get_merge_request.
Inputs: body (required), merge_request_iid (required), base_sha, head_sha, +5 more.
gitlab_create_noteAdd commentA
Posts a comment on an issue, merge request, snippet, epic or commit. Embed uploaded screenshots with the markdown returned by gitlab_upload_file.
Inputs: iid (required), body (required), target_type (required), group_id, +1 more.
gitlab_create_or_update_fileWrite fileB
Creates or updates a single file in a branch.
Inputs: branch (required), content (required), file_path (required), commit_message (required), +5 more.
gitlab_create_projectCreate projectA
Creates a new project, optionally inside a group.
Inputs: name (required), path, topics, visibility, +4 more.
gitlab_create_releaseCreate releaseB
Publishes a release for a tag.
Inputs: tag_name (required), ref, name, milestones, +2 more.
gitlab_delete_issueDelete issueADestructive
Permanently deletes an issue.
Inputs: confirm (required), issue_iid (required), project_id.
gitlab_delete_projectDelete projectADestructive
Deletes (or schedules deletion of) a project. Irreversible on most instances.
Inputs: confirm (required), project_id.
gitlab_download_urlDownload any instance URLARead-only
Authenticated GET of an arbitrary URL on the GitLab instance — job artifacts, raw files, avatars, design files. Returns images as images and text as text.
Inputs: url (required), project_id.
gitlab_fork_projectFork projectC
Forks a project into a namespace.
Inputs: name, path, project_id, namespace_path.
gitlab_get_commitGet commitARead-only
One commit with stats and optionally its diff.
Inputs: sha (required), max_chars, project_id, include_diff.
gitlab_get_fileGet file contentsARead-only
Reads a file from the repository. Text comes back decoded; set as_image=true to look at an image committed to the repo.
Inputs: file_path (required), ref, as_image, project_id.
gitlab_get_groupGet groupCRead-only
Details for one group.
Inputs: group_id (required), with_projects.
gitlab_get_issueGet issueARead-only
Full issue: description, labels, assignees, milestone, plus (by default) every comment and the URLs of every attached screenshot/file. Feed those URLs to gitlab_read_attachment to actually view the images.
Inputs: issue_iid (required), project_id, include_notes, include_attachments.
gitlab_get_job_artifactGet job artifactARead-only
Downloads a CI artifact. A single image path (Playwright/Cypress screenshot, coverage badge) comes back as a viewable image.
Inputs: job_id (required), project_id, artifact_path.
gitlab_get_job_logGet job logARead-only
Downloads the trace/log of a CI job — the fastest way to find out why a pipeline failed. Returns the tail by default.
Inputs: job_id (required), project_id, tail_chars.
gitlab_get_merge_requestGet merge requestARead-only
Full merge request: branches, approvals, merge status, pipeline, plus optional comments and attachment/screenshot URLs.
Inputs: merge_request_iid (required), project_id, include_notes, include_diff_stats, +1 more.
gitlab_get_merge_request_diffGet merge request diffARead-only
The actual code changes of a merge request, file by file. Truncated to stay readable.
Inputs: merge_request_iid (required), paths, max_chars, project_id.
gitlab_get_pipelineGet pipelineBRead-only
A pipeline with its jobs, durations and failure reasons.
Inputs: pipeline_id (required), project_id, include_jobs, include_variables.
gitlab_get_projectGet projectARead-only
Full details for one project, including default branch, namespace and web URL.
Inputs: license, project_id, statistics.
gitlab_get_userGet userBRead-only
Fetches a single user by id.
Inputs: user_id (required).
gitlab_issue_linksIssue linksA
Lists, creates or removes links between issues (relates to / blocks / blocked by).
Inputs: action (required), issue_iid (required), link_type, project_id, +3 more.
gitlab_issue_time_trackingIssue time trackingB
Reads or updates estimate and spent time on an issue.
Inputs: action (required), issue_iid (required), summary, duration, +1 more.
gitlab_job_actionJob actionsBDestructive
Inspects, retries, cancels, runs or erases a CI job.
Inputs: action (required), job_id (required), project_id.
gitlab_lint_ci_configValidate .gitlab-ci.ymlARead-only
Validates CI configuration against the project's context before committing it.
Inputs: content (required), dry_run, project_id.
gitlab_list_attachmentsList attachments of an issue/MRARead-only
Scans the description and comments of an issue, merge request or epic and returns every attached file/screenshot with a ready-to-use URL for gitlab_read_attachment.
Inputs: iid (required), target_type (required), group_id, project_id, +1 more.
gitlab_list_boardsList issue boardsBRead-only
Issue boards and their lists for a project or group.
Inputs: page, limit, group_id, per_page, +2 more.
gitlab_list_branchesList branchesCRead-only
Branches of a project.
Inputs: page, limit, search, per_page, +2 more.
gitlab_list_commitsList commitsCRead-only
Commit history with optional path and date filters.
Inputs: page, path, limit, since, +7 more.
gitlab_list_deploymentsList deploymentsCRead-only
Deployment history of a project.
Inputs: page, sort, limit, status, +5 more.
gitlab_list_discussionsList discussionsARead-only
Threaded discussions, including code-review threads with their file/line position and resolved state.
Inputs: iid (required), target_type (required), page, limit, +3 more.
gitlab_list_environmentsList environmentsDRead-only
Deployment environments of a project.
Inputs: name, page, limit, states, +3 more.
gitlab_list_eventsList eventsBRead-only
Activity stream for the current user or a project (pushes, comments, merges, ...).
Inputs: page, sort, after, limit, +6 more.
gitlab_list_group_membersList group membersDRead-only
Members of a group.
Inputs: group_id (required), page, limit, query, +3 more.
gitlab_list_group_projectsList group projectsARead-only
Projects inside a group, optionally recursing into subgroups.
Inputs: group_id (required), page, limit, search, +4 more.
gitlab_list_groupsList groupsBRead-only
Lists groups visible to the token.
Inputs: page, limit, owned, search, +3 more.
gitlab_list_issuesList issuesARead-only
Lists issues for a project, a group, or the whole instance (omit project_id and group_id) with the usual filters.
Inputs: iids, page, sort, limit, +18 more.
gitlab_list_jobsList CI jobsBRead-only
Jobs of a pipeline or of the whole project.
Inputs: page, limit, scope, per_page, +3 more.
gitlab_list_labelsList labelsCRead-only
Labels of a project or group.
Inputs: page, limit, search, group_id, +3 more.
gitlab_list_merge_requestsList merge requestsARead-only
Lists merge requests for a project, a group, or the whole instance (omit both ids) with the usual filters.
Inputs: wip, page, sort, limit, +17 more.
gitlab_list_milestonesList milestonesCRead-only
Milestones of a project or group.
Inputs: page, limit, state, search, +4 more.
gitlab_list_notesList commentsARead-only
Lists comments (notes) on an issue, merge request, snippet or epic.
Inputs: iid (required), target_type (required), page, sort, +5 more.
gitlab_list_packagesList packagesDRead-only
Packages published to the project registry.
Inputs: page, limit, per_page, all_pages, +3 more.
gitlab_list_pipelinesList pipelinesBRead-only
CI pipelines with status and ref filters.
Inputs: ref, sha, page, sort, +9 more.
gitlab_list_pipeline_schedulesList pipeline schedulesCRead-only
Scheduled pipelines of a project.
Inputs: page, limit, per_page, all_pages, +1 more.
gitlab_list_project_membersList project membersCRead-only
Members of a project, optionally including inherited group members.
Inputs: page, limit, query, per_page, +3 more.
gitlab_list_projectsList projectsARead-only
Lists projects visible to the token, with search and membership filters.
Inputs: page, sort, limit, owned, +9 more.
gitlab_list_protected_branchesList protected branchesBRead-only
Protection rules for branches (who may push/merge).
Inputs: page, limit, per_page, all_pages, +1 more.
gitlab_list_registry_repositoriesList container imagesARead-only
Container registry repositories of a project, optionally with tags.
Inputs: page, tags, limit, per_page, +2 more.
gitlab_list_releasesList releasesCRead-only
Releases of a project.
Inputs: page, limit, per_page, all_pages, +1 more.
gitlab_list_repo_treeList repository filesBRead-only
Lists files and directories in the repository tree.
Inputs: ref, page, path, limit, +4 more.
gitlab_list_tagsList tagsCRead-only
Repository tags.
Inputs: page, limit, search, per_page, +2 more.
gitlab_list_todosList todosARead-only
Lists the authenticated user's todo items (assignments, mentions, review requests).
Inputs: page, type, limit, state, +4 more.
gitlab_list_usersList usersARead-only
Searches instance users by username or free text.
Inputs: page, limit, active, search, +3 more.
gitlab_markdown_renderRender markdownARead-only
Renders markdown through GitLab so relative upload links and issue references are expanded to absolute URLs — handy before downloading attachments.
Inputs: text (required), gfm, project_id.
gitlab_mark_todo_doneMark todo(s) doneA
Marks a single todo as done, or all pending todos when todo_id is omitted.
Inputs: todo_id.
gitlab_merge_merge_requestMerge merge requestADestructive
Merges a merge request, optionally waiting for the pipeline to pass.
Inputs: merge_request_iid (required), sha, squash, project_id, +4 more.
gitlab_merge_request_actionMerge request actionsA
Approve/unapprove, rebase, cancel auto-merge, or inspect approvals, commits, participants, closed issues and pipelines of a merge request.
Inputs: action (required), merge_request_iid (required), project_id.
gitlab_pipeline_actionPipeline actionsADestructive
Triggers a new pipeline, or retries/cancels/deletes an existing one.
Inputs: action (required), ref, variables, project_id, +1 more.
gitlab_project_hooksProject webhooksCDestructive
Lists, creates and deletes project webhooks.
Inputs: action (required), url, token, hook_id, +5 more.
gitlab_project_statisticsProject statisticsBRead-only
Languages, contributors and repository size for a project.
Inputs: project_id.
gitlab_read_attachmentRead attachment / screenshotARead-only
Downloads an attached file from GitLab with authentication and returns it. PNG/JPEG/GIF/WebP images come back as viewable images, text files as text, anything else as a base64 resource. This is how you look at screenshots pasted into issues, merge requests and comments.
Inputs: url (required), project_id.
gitlab_reply_to_discussionReply in threadB
Adds a reply to an existing discussion thread.
Inputs: iid (required), body (required), target_type (required), discussion_id (required), +1 more.
gitlab_resolve_merge_request_threadResolve MR threadA
Marks a review thread resolved or unresolved.
Inputs: resolved (required), discussion_id (required), merge_request_iid (required), project_id.
gitlab_searchSearch GitLabARead-only
Global, group or project search across projects, issues, merge requests, code blobs, commits, wiki and notes.
Inputs: scope (required), search (required), ref, page, +5 more.
gitlab_snippetsProject snippetsC
Manages project snippets, including raw content.
Inputs: action (required), title, content, file_name, +4 more.
gitlab_tag_actionTag actionsCDestructive
Creates or deletes a tag.
Inputs: action (required), tag_name (required), ref, message, +1 more.
gitlab_update_issueUpdate issueA
Edits an issue, including closing/reopening it.
Inputs: issue_iid (required), title, labels, weight, +9 more.
gitlab_update_merge_requestUpdate merge requestC
Edits a merge request.
Inputs: merge_request_iid (required), title, labels, squash, +10 more.
gitlab_update_noteEdit commentC
Edits an existing comment.
Inputs: iid (required), body (required), note_id (required), target_type (required), +1 more.
gitlab_update_projectUpdate projectC
Edits project settings.
Inputs: name, topics, archived, project_id, +6 more.
gitlab_upload_fileUpload file to projectA
Uploads a local file to the project's upload store and returns the markdown snippet to embed it in an issue, MR or comment.
Inputs: file_path (required), filename, project_id.
gitlab_whoamiCurrent user & instanceARead-only
Returns the authenticated user, the configured GitLab instance URL and the instance version. Use this first to verify GITLAB_URL/GITLAB_TOKEN are wired correctly.
Inputs: no named parameters.
gitlab_wikiProject wikiB
Lists, reads and edits wiki pages of a project.
Inputs: action (required), slug, title, format, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 85 tools
Many tools target distinct resources, but several have overlapping purposes: the generic 'action' tools (e.g., gitlab_branch_action, gitlab_merge_request_action) bundle multiple operations, and download-style tools (gitlab_download_url, gitlab_read_attachment, gitlab_get_job_artifact) have fuzzy boundaries. Descriptions help, but an agent may struggle to pick between similar tools like gitlab_list_notes and gitlab_list_discussions.
Most tools follow gitlab_verb_noun, but there are notable exceptions: noun-only tools (gitlab_wiki, gitlab_snippets), noun+action tools (gitlab_branch_action, gitlab_pipeline_action), and unique names (gitlab_whoami, gitlab_markdown_render). While the uniform prefix helps, the mixing of verb forms creates an inconsistent pattern.
With 85 tools, this set far exceeds even the 'too many' threshold (25+). While a comprehensive GitLab API wrapper could justify breadth, the sheer number makes the tool surface unwieldy for an agent to navigate effectively.
The surface covers a wide range: projects, groups, issues, MRs, notes, repository files, branches, commits, pipelines, jobs, artifacts, wiki, snippets, and more. Minor gaps exist (e.g., no group create/update/delete tools, epics only via api_request), but the core lifecycle and operational workflows are well covered.
Maintenance
Related MCP Connectors
Go MCP server for GitLab: 2 dynamic tools reach 1000+ REST/GraphQL actions. Free/CE, no paid tier.
Unofficial GitLab MCP — wraps the GitLab REST API v4 (BYO API key)
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
A MCP server built for developers enabling Git based project management with project and personal…
Related MCP Servers
- AlicenseBqualityCmaintenanceA Model Context Protocol server that enables AI assistants to interact with self-hosted GitLab instances through 30 specialized tools. It supports managing projects, merge requests, CI/CD pipelines, and repository operations via the GitLab REST API v4.30MIT
- 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
- AlicenseCqualityBmaintenanceMCP server for interacting with GitLab API, supporting dynamic tool selection and enterprise-grade security.20810MIT