gitlab-mcpl
Polls a self-managed GitLab instance (via a personal access token) to expose scoped read/write tools and polling events to an MCP host. Provides read tools for merge requests, discussions, pipelines, job logs, issues, code search, files and repository trees; write tools for commenting, replying in threads, editing/deleting own comments, sticky comments, creating/editing merge requests, requesting reviews, rebasing, and merge-at-SHA; and event streams for to-dos, own-MR notes/approvals, and pipeline completion/failure (including failed job details and optional bounded log tails).
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
gitlab-mcpl
Polling MCPL connector for self-managed
GitLab. Node ≥22.12, TypeScript, MIT. API fixtures target GitLab 17.11, Free tier; validate your own version.
Uses @animalabs/mcpl-core to expose scoped read/write tools and polling
events to an MCP/MCPL host. No webhook listener or GitLab SDK is required.
Validation status: automated fixture/API and real MCPL stream tests only. No live GitLab instance was available; slow/unreachable startup has not been verified live (only with local fixtures). Do not treat these tests as certification of protected-branch behavior, GitLab timing, or your deployment permissions. See Design notes for polling limitations.
Run
npm ci --cache .npm-cache
npm run build
npm test
install -d -m 700 "$HOME/.config/gitlab-mcpl"
# Put your PAT in ~/.config/gitlab-mcpl/token without placing it in shell history.
chmod 600 "$HOME/.config/gitlab-mcpl/token"
export GITLAB_URL=https://example.gitlab.com
export GITLAB_TOKEN_FILE="$HOME/.config/gitlab-mcpl/token"
export GITLAB_PROJECTS=group/project
export GITLAB_EXPECT_USERNAME=example-user
export GITLAB_PIPELINE_EVENT_LOG_BYTES=4096
export GITLAB_STATE_FILE="$HOME/.config/gitlab-mcpl/state.json"
node dist/src/index.js --stdio
# Or: node dist/src/index.js --tcp 8787 (127.0.0.1 only, one host at a time)Scope examples
The run example above is list mode: GITLAB_PROJECTS=group/project.
To track bounded reviewer heads as well, use:
export GITLAB_PROJECTS=group/project,group/other-project
export GITLAB_READ_ALLOW=group/project,group/other-project
export GITLAB_EVENT_SOURCES=todos,own-mrs,pipelines,reviewing
export GITLAB_PIPELINE_EVENT_LOG_BYTES=4096
# List mode uses PROJECTS for write scope; leave WRITE_ALLOW and EXCLUDE unset.For all-projects events with excludes, replace those scope settings with:
export GITLAB_PROJECTS='*'
export GITLAB_PROJECTS_EXCLUDE='private-group/*,group/excluded-project,1234'
export GITLAB_READ_ALLOW='group/*'
export GITLAB_FEATURE_SETS=gitlab.events,gitlab.read
export GITLAB_EVENT_SOURCES=todos,own-mrs,pipelines
export GITLAB_PIPELINE_EVENT_LOG_BYTES=4096
# Only if enabling write feature sets (api PAT required):
# export GITLAB_WRITE_ALLOW=group/project
# export GITLAB_MR_TARGET_ALLOW=group/project:mainDo not combine * with a project list. Excludes restrict events and writes,
not independently allowed reads. reviewing and threads require list mode.
Use a dedicated regular user, one process and one state file per account.
The token must have read_api for read/events, or api for any declared write
set. write_repository alone does not authenticate REST. Before serving, startup
validates local configuration, /user (including
GITLAB_EXPECT_USERNAME), PAT scopes via /personal_access_tokens/self, and
the state file's instance/numeric-user binding and initial persistence. These
fail fast so a wrong account, insufficient token or mismatched state cannot be
advertised as usable. A slow/unreachable identity or PAT endpoint therefore still
blocks/fails startup. /version diagnostics, project/subsidiary scope resolution
and persisted-watch revalidation run after stdio is attached or TCP listens;
initialize, ping and tools/list do not wait for them. Until project validation
finishes, event/write-scope operations return not-ready and authorize nothing;
explicit GITLAB_READ_ALLOW reads are independent. Every normal/hot poll waits
for successful scope and persisted-state validation, retrying on later passes.
Unvalidated persisted watches never drive pipeline reads or event delivery.
Tokens with fewer than 14 days remaining generate a warning and an event
when the host grants events. Rotate tokens out of band and restart; no automatic
rotation. Never put a PAT in an environment variable or command-line argument.
Plain MCP supports the configured tools except merge, but has no polling,
channels, push events, or rollback protocol. MCPL advertises its manifest only
when negotiated and grants nothing before a grant-bearing
featureSets/update Request. Notification-form updates can only reduce authority.
Comments declare both tools and channels.publish, matching the sibling's
contract; a tool-only MCPL host must grant both to enable that set.
Related MCP server: GitLab MCP Server
CI prerequisites
If the test project has CI/CD disabled, enable it in the project's
Settings → General → Visibility, project features, permissions
(builds_access_level: enabled) before testing pipelines. A runner must be
available to the project and permitted on the branch. If runners require tags,
set matching tags in each .gitlab-ci.yml job (or under default); otherwise
jobs may stay pending. Use your runner's actual tags.
Failure-event log tails are opt-in: GITLAB_PIPELINE_EVENT_LOG_BYTES defaults
to 0 (off); the examples use 4096. ANSI controls and GitLab section markers
are stripped before the useful-text byte cap; ordinary runner prose remains.
Tool surfaces
Default: gitlab.events,gitlab.read. Writes are explicit opt-ins.
Feature set | Tools |
| Polling events, no tools |
|
|
|
|
|
|
|
|
|
|
|
|
gitlab.review and gitlab.issues writes are deferred, not silently accepted.
There is no approve, raw API, repository-write, auto-merge, cancel-auto-merge,
merge-ref, or webhook surface.
Examples (tool arguments, before any host tool-name prefix):
{"project":"group/project","iid":3,"include":"diff,discussions,approvals"}
{"project":"group/project","pipeline_id":123}
{"project":"group/project","job_id":456,"grep":"ERROR","context":2}
{"group":"group","query":"function_name","ref":"main"}
{"thread":"gitlab:group/project!3","body":"Update: tests passed."}
{"thread":"gitlab:group/project!3","thread_id":"d:0123456789abcdef0123456789abcdef01234567","body":"Reply"}
{"project":"group/project","iid":3,"draft":false}MR channels are gitlab:<nested/path>!<iid>; issue channels use #<iid>.
Discussion threads are d:<40-hex-id>. @pipelines and @branches are read-only
project channels. Channels register lazily on an event, tool touch, or open.
channels/open accepts an id or {project,number,kind:"mr"|"issue"} address;
optional history is capped at 100 notes, with beforeMessageId support.
Opening a channel needs the project in event scope; history with a nonzero
limit is a read and additionally needs GITLAB_READ_ALLOW (refused otherwise,
before the channel is registered).
sinceLastSeen is explicitly unsupported. Typing is a granted no-op.
Comments are owned by numeric user id, never a username or bot flag.
Sticky comments use a simple marker key and only update this user's matching
note. MCPL comment writes return a checkpoint after the write. Rollback deletes
created notes and restores edited text; deleted notes cannot be undeleted and
are reported as irreversible. Rollback rechecks project scope and note ownership.
Failed undo work remains retryable; the journal stays intact during remote undo.
Events and safety
The default sources are pending and done to-dos, own-MR notes/approvals,
and pipelines matching own MRs or recently merged own MRs. Reviewer heads,
reviewed-MR merge/close, watched branch heads, and full project threads are opt-in.
Hot polling follows active own/reviewer head pipelines.
GITLAB_PROJECTS=* opts in to events from every project the token can see,
minus GITLAB_PROJECTS_EXCLUDE; see all-projects mode.
* widens events only: reads still follow GITLAB_READ_ALLOW, and writes are
allowed only in projects named in GITLAB_WRITE_ALLOW, which * never implies.
Startup refuses any write feature set in that mode without GITLAB_WRITE_ALLOW.
It also requires an explicit GITLAB_READ_ALLOW and project-qualified target
allow-lists, and refuses the reviewing and threads sources. Failed pipeline events
include failed job ids, names, stages, URLs and reasons; up to three optional
bounded log tails. Watched jobs produce separate events.
Pipeline completion is not attributed to its triggering user: that would
incorrectly mute failures on the agent's own pipelines as fromSelf.
chat:from-self is numeric identity only. No agent-user/bot suppression exists.
Recipes show self-first wake policies with neutral placeholders.
Use recipe-list.json with list.env for bounded per-project reviewing;
recipe-read-only-list.json is a read-only list-mode host recipe.
The recipe-all-projects.json / all-projects.env and
recipe-writes-all-projects.json / writes-all-projects.env pairs use
GITLAB_PROJECTS=*, explicit read authority, and explicit write authority where
writes are enabled. Adapt placeholder paths and select the matching env via
GITLAB_MCPL_ENV_FILE; gitlab.merge stays off. All-projects recipes use to-dos
for reviewer assignment, not the unsupported per-project reviewing/threads
sources; use list mode for reviewer head tracking.
All HTTP requests pass a static method/template allow-list. Every outgoing
string is quick-action neutralised, including channel publish, descriptions,
and rollback restorations. All command-looking lines (^\s*/\w) get a zero-width
space after /; there is no bypass. Tool schemas reject arbitrary extra fields.
Redirects are refused and pagination never follows server-provided URLs.
Merge requires all three: configured gitlab.merge, nonempty
GITLAB_MERGE_TARGET_ALLOW, and an MCPL Request explicitly enabling
gitlab.merge (a blanket tools capability is insufficient). It checks author,
exact 40-hex head SHA, target, no existing auto-merge, successful head pipeline
by default, and detailed_merge_status. The only merge body fields are sha
and configured should_remove_source_branch. 401/403/405/409/422 have explained
refusals; 405/409/422 re-read state. There is never an automatic merge retry.
Attempts/outcomes are audited to stderr and state, with no rollback.
The SHA is checked atomically by GitLab. Target, author and other preflight conditions are not atomically pinned by GitLab's merge API: concurrent MR retargeting remains a deployment/reviewer concern. Account permissions outside this connector are not restricted by it.
CI retries fail closed on 17.11
retry_pipeline and retry_job currently refuse all requests, even with an
explicit ref allow-list. Pipeline completion can execute a human-armed auto-merge.
GitLab's worker considers associated MRs across projects, not just MRs visible
to this token; a visible-MR preflight cannot prove safety or prevent concurrent
arming. The retry HTTP routes are disabled too. Use GitLab directly for retries
until a server-side safety mechanism can uphold the connector's no-merge boundary.
No auto-merge is cancelled or modified by the connector.
Configuration and operations
See all environment variables, deployment examples, Design notes, and the isolated live-test kit (env). Read scope is separate from write/event scope. In all-projects mode read, write and event scope are three separate settings and none is derived from another. Group code search fans out to read-allowed projects because Free GitLab cannot do group blob search.
State includes note bodies needed for rollback, poll cursors, a 2,000-entry dedup ring for other events, a separate set of still-pending/recent to-do identities, watched SHAs, discussion/reviewer markers and a 1,000-entry merge audit. It is atomically replaced in mode 600. Protect its directory; do not share it between processes. Missing/corrupt state starts empty with a warning (inherited sibling behavior); expect replay and loss of rollback reach. State is bound at startup to the instance URL and numeric user id; mismatches are refused. Never restore a state file from a different instance/user. Without a state file it is in memory.
The state file may outlive the configuration that wrote it. At load, before
every poll pass and before every hot poll, persisted hot pipeline watches are
revalidated against the current GITLAB_EVENT_SOURCES and event scope
(GITLAB_PROJECTS, or * minus GITLAB_PROJECTS_EXCLUDE) and dropped if
they fail; own-MR/own-merge interest sets and poll cursors of a disabled
source or an out-of-scope project are dropped at the first check. A source or
project enabled again later therefore starts from a fresh window rather than
catching up from its old cursor. If a scope decision cannot be made (GitLab
unreachable in all-projects mode), nothing is polled until it can.
GET retries are bounded (three attempts), respecting Retry-After or
RateLimit-Reset; delays over 60 seconds are returned as errors for later retry.
Writes never retry automatically. After a timeout, disconnect, or server 5xx,
inspect GitLab before repeating a write: it may have succeeded without an answer.
A crash between a successful write and journaling can also lose undo information.
Poll sources advance only after successful complete reads and accepted delivery;
failed sources retain their own cursor, including a persisted first-pass lower bound.
Pending to-do identities are retained until absent from a complete pending read
and older than the completed-to-do overlap window; they are not ring-evicted.
Notes pagination requires numeric X-Next-Page metadata (empty means last page);
missing or malformed metadata fails the source rather than silently truncating it. No polling runs without an event grant.
Each event can be delivered on two paths: channels.incoming and
pushEvents. Each path is deduped separately, not against the other path:
a host with both enabled shows the event twice. Prefer channels.incoming for channel-native delivery: explicitly select
gitlab.events and grant channels.register as well. The default
gitlab.events declaration uses pushEvents; hosts must choose the channel
path explicitly rather than relying on that default. Use pushEvents instead
for hosts that only support push/wake alerts. Do not enable both unless the host deliberately reconciles the copies.
Wake policies matching both scopes are compatibility matches, not deduplication.
Partial push/channel success retries only the failed path during the connection.
A crash before durable acknowledgement can replay an event; hosts should dedup
by eventId/messageId. This is at-least-once, not exactly-once delivery.
Read output and pagination
Read tools return compact fields by default (ids, status, refs/SHAs, URLs,
actors, failure reasons and relevant text), not entire GitLab user objects.
list_merge_requests, list_pipelines, list_discussions, list_tree, and
search_code return {items, page, limit, next_page, output_truncated}.
The default is one page of 20 rows; set page and limit (1–100) to fetch more.
next_page is conservative: a full final page can point to an empty next page.
No tool pagination changes polling or write-preflight pagination.
get_merge_request defaults to metadata only, in data. Explicit
include: "diff,discussions,approvals" requests those extras. page/limit
apply to diffs and discussions; diffs_page reports diff continuation.
get_pipeline returns compact pipeline.data plus a paged jobs envelope.
get_issue also returns {data, output_truncated}.
Use full: true to include additional API fields. Both modes cap each string
at 4,000 UTF-8 bytes, nested arrays at 100 entries and depth at 10, with a
roughly 60 KB data budget per component (group searches share that budget
across projects). output_truncated flags size/depth clipping, not intentional
compact-field omission. Lower limit to recover rows clipped by a byte budget;
use get_file for source contents and get_job_log for bounded log tails.
This changes the earlier raw-array/raw-object read result shapes.
search_code.group means a GitLab group, not a user namespace. For a
user-owned repository use project: "username/repository"; a group 404 may
also mean the group is missing or inaccessible. Job logs strip ANSI controls
and GitLab section markers before literal grep; section heading text remains.
Full environment reference
Lists are comma-separated. Unknown feature sets/tools and invalid values are
startup errors, aggregated where possible. Every GITLAB_PROJECTS entry must
resolve. Pipeline projects and branch watches must be inside that write/event
scope. Project selectors accept numeric ids or full nested paths; target-allow
entries use branch or canonical group/project:branch (exact, no glob).
Source/job globs support * (zero or more characters); other characters are literal.
Variable | Default / behavior |
| Required HTTPS origin/base path; |
| Required regular mode-600 PAT file; whitespace-only/embedded-whitespace tokens refused. |
| Optional startup identity check. |
| Optional PEM trust bundle for this connection, replacing default roots. Otherwise Node default trust applies (normally bundled Mozilla roots, NOT necessarily the host system store). For an internal CA on Debian/Ubuntu set |
|
|
|
|
| Required write/event allow-list, no globs/groups. Exactly |
| Empty; only valid with |
| Empty; only valid with |
| Same as projects; exact path/id, |
|
|
| Empty; removes named tools, also from channel publication routes. |
| Empty: cannot create/retarget any MR. |
| Empty: any branch not in target allow-list. Otherwise a |
|
|
| Empty. Retained for compatibility, but CI retry tools currently fail closed regardless of this value (see README). |
| Empty; required when merge set declared. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Empty; |
| Default |
|
|
| Same as projects; must be a subset. With |
|
|
| Empty usernames of triggering users (e.g. project-token account). |
| Empty exact refs (e.g. |
|
|
|
|
| Empty; comma-separated |
|
|
|
|
|
|
| Empty usernames; optional maintainer tag only, not authority. |
|
|
| Unset = in memory; strongly recommended to set for restart continuity. |
|
|
GITLAB_WEBHOOK_*, GITLAB_AGENT_USERS, and GITLAB_SHARED_ACCOUNT are refused:
This connector supports polling only and numeric-user self identity, not bot or
shared-account heuristics. Prefer dedicated accounts.
The Bash launcher deploy/gitlab-mcpl additionally reads GITLAB_MCPL_ENV_FILE
(default $HOME/.config/gitlab-mcpl/env). It sources this operator-owned file;
use shell quoting there, not systemd EnvironmentFile syntax.
Design notes
Polling cannot recover intermediate transitions that occur entirely between observations. Own open merge requests are fully enumerated and hydrated each pass, increasing API traffic. Hot polling is serialized and best-effort; slow I/O can exceed the configured interval. Marker maps and rollback history grow with activity; monitor and protect the state file.
Attribution
Code and tests are copied/adapted from github-mcpl, commit
7958055c8ee051e79ddc3c7c38ef9f458bf8006e, under the MIT license (see LICENSE).
This includes grant/error handling, state lineage, journaling, persistence and
state tests, plus the MCPL handshake, feature/ontology builders, per-channel
queue, event pipeline, comment/sticky/rollback algorithms and duplex fake-host
pattern adapted to GitLab contracts.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Unofficial GitLab MCP — wraps the GitLab REST API v4 (BYO API key)
One OAuth connector for your team's remote MCP servers, with Tool Packs, guardrails and logs.
Hosted Meta ads MCP with OAuth, bounded reads, and prepare/confirm writes.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceFull-coverage GitLab MCP server with 44 tools across 18 resource types. Agent-optimized CQRS design — one tool call handles complete multi-step operations. Supports OAuth 2.1, read-only mode, stdio/SSE/StreamableHTTP transports, and GraphQL-native work items with full hierarchy (epics,issues,etc)8Apache 2.0
- FlicenseBqualityDmaintenanceProvides tools to interact with a self-hosted GitLab instance, enabling project, issue, note, search, todo, and wiki page management through MCP.161-
- FlicenseNot gradedqualityDmaintenanceEnables read-only access to GitLab projects, files, directories, and merge requests through MCP tools.-
- AlicenseCqualityBmaintenanceEnables secure interaction with GitLab instances through MCP, supporting projects, merge requests, issues, pipelines, and search.632AGPL 3.0