gitlab-ci-mcp
gitlab-ci-mcp
用于 GitLab CI/CD 的 MCP 服务器。允许 LLM 代理(Claude Code、Cursor、OpenCode、DevX Agent 等)处理流水线、作业、计划任务、分支、标签、合并请求和仓库文件。
Python,FastMCP,stdio 传输。
适用于任何 GitLab — SaaS gitlab.com 或自托管/本地部署。专为企业网络设计:可配置的 NO_PROXY 处理、可选的 SSL 验证开关、通过环境变量实现的项目级作用域。
设计亮点
工具注解 — 每个工具都带有
readOnlyHint/destructiveHint/idempotentHint/openWorldHint,以便 MCP 客户端可以对操作进行分类(例如,仅在gitlab_merge_mr、gitlab_delete_schedule等破坏性操作时请求确认)。每个工具的结构化输出 — 每个工具都声明了 TypedDict 返回类型,因此 FastMCP 会自动生成
outputSchema,并且每个结果除了预渲染的 markdown 文本块外,还携带structuredContent。能够渲染结构化数据的客户端会使用它;偏好紧凑文本的代理则获取 markdown。无需response_format参数。结构化错误 — 身份验证、404、403、429(速率限制)、5xx、缺少环境变量等错误会被转换为可操作的
ToolError消息(例如:“GitLab 身份验证失败……请验证 GITLAB_TOKEN 是否具有api作用域”)并作为isError=True的结果呈现。Pydantic 输入验证 — 每个参数都有类型约束(范围、长度、字面量),并自动作为 JSON Schema 公开。
按调用进行项目作用域划分 — 每个工具都接受一个可选的
project_path,它会覆盖GITLAB_PROJECT_PATH以进行跨项目查询。分页 — 列表工具返回一个包含
page、total、has_more、next_page的pagination块,并在 markdown 页脚中提供下一页提示。MCP 上下文集成 —
gitlab_pipeline_health和gitlab_get_job_log是async的,并通过 MCP 上下文发出info日志 /report_progress事件,以便客户端可以显示进度条。MCP 资源 —
gitlab://project/info和gitlab://project/ci-config为偏好资源模型而非工具的客户端提供了常见的查找功能。生命周期管理 —
python-gitlabHTTP 会话通过asynccontextmanager生命周期钩子在服务器关闭时被妥善关闭。日志 grep —
gitlab_get_job_log接受grep_pattern+grep_context(周围行),用于对兆字节级的 CI 日志进行正则过滤,而无需将整个跟踪拉入代理上下文。
线程模型
FastMCP 会自动在工作线程中运行同步工具(anyio.to_thread.run_sync),因此它们不会阻塞 asyncio 事件循环 — python-gitlab 是一个同步库,如果我们自己将每个调用包装在 asyncio.to_thread 中会显得过于繁琐。受益于 MCP 上下文(进度、信息日志)的工具被编写为 async def,并显式地用 asyncio.to_thread 包装 python-gitlab 调用。
Related MCP server: gitlab-mcp
功能
23 个工具涵盖了日常 CI/CD 的方方面面:
流水线
gitlab_list_pipelines · gitlab_get_pipeline · gitlab_get_pipeline_jobs · gitlab_get_job_log · gitlab_trigger_pipeline · gitlab_retry_pipeline · gitlab_cancel_pipeline · gitlab_pipeline_health
计划任务
gitlab_list_schedules · gitlab_create_schedule · gitlab_update_schedule · gitlab_delete_schedule
分支与标签
gitlab_list_branches · gitlab_list_tags · gitlab_compare_branches
合并请求
gitlab_list_merge_requests · gitlab_get_merge_request · gitlab_get_merge_request_changes · gitlab_create_merge_request · gitlab_merge_mr
仓库与项目
gitlab_get_file · gitlab_list_repository_tree · gitlab_project_info
流水线健康报告
gitlab_pipeline_health 返回 7/30 天内易于阅读的摘要:
Last 7d: 96.4% up | 27/28 success
Last 30d: 92.1% | 105/114 success
Last 10: success success success failed success ...对于值班/分类非常方便:покажи health master за последние 7 дней。
安装
需要 Python 3.10+。
# via uvx (recommended)
uvx --from gitlab-ci-mcp gitlab-ci-mcp
# or via pip/pipx
pipx install gitlab-ci-mcp配置
所有配置均通过环境变量进行:
变量 | 必需 | 描述 |
| 是 | 基础 URL,例如 |
| 是 | 具有 |
| 是 | 默认项目,例如 |
| 否 |
|
| 否 | 要添加到 |
每个工具都接受一个可选的 project_path 参数,该参数会覆盖每次调用的 GITLAB_PROJECT_PATH — 这对于跨项目查询非常有用。
Claude Code
完整演练: docs/claude-code.md — 先决条件、两种安装路径、多项目设置、企业代理后的自托管 GitLab、故障排除、卸载。
简短版本:
claude mcp add gitlab uvx --from gitlab-ci-mcp gitlab-ci-mcp \
--env GITLAB_URL=https://gitlab.example.com \
--env GITLAB_TOKEN=glpat-xxxxxx \
--env GITLAB_PROJECT_PATH=my-org/my-repo或者在 ~/.claude.json / 项目 .mcp.json 中:
{
"mcpServers": {
"gitlab": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "gitlab-ci-mcp", "gitlab-ci-mcp"],
"env": {
"GITLAB_URL": "https://gitlab.example.com",
"GITLAB_TOKEN": "${GITLAB_TOKEN}",
"GITLAB_PROJECT_PATH": "my-org/my-repo",
"GITLAB_SSL_VERIFY": "true"
}
}
}
}检查:
claude mcp list
# gitlab: uvx --from gitlab-ci-mcp gitlab-ci-mcp - ✓ ConnectedCursor / OpenCode / DevX Agent
同样的思路 — 将 MCP 配置指向 uvx --from gitlab-ci-mcp gitlab-ci-mcp 并使用上述环境变量。请参阅每个工具自己的 MCP 配置语法。
示例提示词
что сломалось в последнем pipeline masterпокажи health master за 7 дней для проекта my-org/other-repoсоздай MR из feature/foo в master с title "feat: foo"покажи содержимое .gitlab-ci.yml из master速率限制与连接重用
GitLab 强制执行每用户速率限制(REST API 通常为每小时 2000 次请求,可由管理员配置 — 请参阅您实例的 /admin/application_settings/network)。
服务器为每个
project_path缓存一个python-gitlabHTTP 会话,因此针对同一项目的重复工具调用会重用连接,而不会每次都重新进行身份验证。列表工具默认
per_page=20,以将单次调用保持在较少的 API 请求数内。如果遇到
429 Too Many Requests,错误处理程序会返回一条可操作的消息 — 请稍候并尝试使用更大的per_page或更少的调用次数重试。
企业代理后的自托管 GitLab
当您的笔记本电脑有本地 HTTP 代理(例如用于企业 Web 访问的 http://127.0.0.1:3128)但 GitLab 在内网时,代理会拦截并终止内部请求。有两种选择:
设置
GITLAB_NO_PROXY_DOMAINS— 服务器将在启动时将它们添加到NO_PROXY并从其自身进程中清除HTTP_PROXY/HTTPS_PROXY,这样它们就不会影响 GitLab 流量。在 MCP
env部分显式传递空的HTTP_PROXY=""等。
开发
git clone https://github.com/mshegolev/gitlab-ci-mcp
cd gitlab-ci-mcp
python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest直接运行服务器(stdio 传输,等待 stdin 上的 MCP 消息):
GITLAB_URL=... GITLAB_TOKEN=... GITLAB_PROJECT_PATH=... gitlab-ci-mcp许可证
MIT — 请参阅 LICENSE。
致谢
基于 python-gitlab 和 MCP Python SDK 构建。
Available Tools
24 toolsgitlab_cancel_pipelineADestructiveIdempotent
Cancel a running pipeline. In-flight jobs will be interrupted.
Destructive for in-progress work. Cancelling an already-finished pipeline is a no-op.
Examples:
- "Pipeline 123 is stuck, cancel it" → pipeline_id=123
- Don't use on finished pipelines — no effect; use gitlab_retry_pipeline
if you want to rerun it.
Inputs: pipeline_id (required), project_path (required). Returns: ref, status, web_url, created_at, +2 more
gitlab_ci_mcp_check_updatesBRead-onlyIdempotent
Check updates when enabled; defaults off and never installs or runs at startup.
Inputs: no named parameters. Returns: cached, detail, status, release_url, +4 more
gitlab_compare_branchesARead-onlyIdempotent
Compare two branches — returns up to 30 commits and the list of changed files.
Use for "what's in release/x.y vs master?" or for release-note drafting.
Examples:
- "What's new in release/1.5 vs master" → source='release/1.5', target='master'
- Don't use to fetch full diffs of an MR — use gitlab_get_merge_request_changes.
Inputs: source (required), project_path (required), target. Returns: source, target, commits, diffs_count, +2 more
gitlab_create_merge_requestA
Create a merge request from source_branch into target_branch.
Not idempotent: creates a new MR each call. Check existing MRs first
via gitlab_list_merge_requests if you want to avoid duplicates.
Examples:
- "Open an MR from feature/login to master" → source_branch='feature/login'
- "Open a WIP MR with a label" → title='Draft: ...', labels=['wip']
- Don't use to merge an already-open MR — use gitlab_merge_mr.
Inputs: project_path (required), source_branch (required), title, labels, +3 more. Returns: iid, hint, state, title, +6 more
gitlab_create_scheduleA
Create a new CI/CD schedule with the given cron and variables.
Not idempotent: duplicate calls create duplicate schedules with auto-incrementing IDs.
Examples:
- "Schedule a nightly build on master at 02:00 Europe/Berlin" →
description='Nightly build', cron='0 2 * * *', ref='master',
timezone='Europe/Berlin', variables={'NIGHTLY': '1'}
- Don't use to update existing schedules — use gitlab_update_schedule.
Inputs: cron (required), variables (required), description (required), project_path (required), +3 more. Returns: ref, cron, active, status, +2 more
gitlab_delete_scheduleADestructiveIdempotent
Delete a schedule by ID. Cannot be undone.
Examples:
- "Delete schedule 42" → schedule_id=42
- If you only want to pause it temporarily, call gitlab_update_schedule
with active=False instead.
Inputs: schedule_id (required), project_path (required). Returns: ref, cron, active, status, +2 more
gitlab_get_fileARead-onlyIdempotent
Read a text file from the repository, truncated to 500 lines.
For binaries, gets decoded as UTF-8 with errors replaced — you will likely get garbage; use for text content only.
Examples:
- "Show me .gitlab-ci.yml on master" → file_path='.gitlab-ci.yml'
- "Read src/app.py from the release-1.2 tag" → file_path='src/app.py', ref='release-1.2'
- Don't use for listings — use gitlab_list_repository_tree.
Inputs: file_path (required), project_path (required), ref. Returns: ref, size, content, file_path, +2 more
gitlab_get_job_logARead-onlyIdempotent
Fetch the trace/log of a job, with optional regex filter.
Two modes:
Default: return the last
taillines (token-efficient, good for "why did this just fail?").With
grep_pattern: return only matching lines withgrep_contextsurrounding lines on each side — ideal for finding "ERROR" / "Traceback" in megabyte-scale CI logs without pulling the whole trace into context.
Examples:
- "Why did job 789 fail" → default tail=100, look at the end of the log
- "Show me the first stage output of job 789" → tail=5000 and scan for stage separator
- "Find every Traceback in job 789" → grep_pattern='Traceback', grep_context=5
- "All ERROR lines from job 789" → grep_pattern='ERROR|FAIL'
Inputs: job_id (required), project_path (required), tail, grep_context, +1 more. Returns: log, job_id, truncated, bytes_read, +6 more
gitlab_get_merge_requestARead-onlyIdempotent
Get full information about a merge request by internal ID (iid).
Includes state, branches, author, assignees, reviewers, labels, conflict status, description and timestamps.
Examples:
- "Show me the description and state of !42" → mr_iid=42
- Don't use to see changed files — use gitlab_get_merge_request_changes.
Inputs: mr_iid (required), project_path (required). Returns: iid, state, title, author, +13 more
gitlab_get_merge_request_changesARead-onlyIdempotent
List changed files in a merge request with truncated diffs (2KB per file).
Useful for code-review-style queries ("what changed in !42?"). Diffs beyond
2KB are truncated — fetch the raw file via gitlab_get_file for full
content.
Examples:
- "What did MR !42 change" → mr_iid=42
- If you need full content of a changed file, use gitlab_get_file
with the MR's source branch.
Inputs: mr_iid (required), project_path (required). Returns: files, title, mr_iid, files_count, +4 more
gitlab_get_pipelineARead-onlyIdempotent
Get a single pipeline with full timing details.
Useful right after gitlab_list_pipelines — lists only return summaries.
Returns status, ref, source, durations (queued/total), and started/finished timestamps.
Examples:
- "Why was pipeline 123 slow" → check queued_duration and duration fields
- "Is pipeline 456 still running" → look at status
- Don't use to see individual jobs — use gitlab_get_pipeline_jobs.
Inputs: pipeline_id (required), project_path (required). Returns: id, ref, source, status, +7 more
gitlab_get_pipeline_jobsARead-onlyIdempotent
List jobs of a pipeline with stage, status, duration and web URL.
Use after noticing a failed pipeline to drill down into which specific job
broke and fetch its log via gitlab_get_job_log.
Examples:
- "What jobs are in pipeline 123" → pipeline_id=123
- "Which job failed in pipeline 456" → filter result by status='failed' client-side
- Don't use for overall pipeline status — use gitlab_get_pipeline instead.
Inputs: pipeline_id (required), project_path (required). Returns: jobs, jobs_count, pipeline_id
gitlab_list_branchesARead-onlyIdempotent
List branches of a project, optionally filtered by substring.
Includes default, protected and merged flags, and the short id
of the tip commit with its title and date.
Examples:
- "List all branches with 'release' in name" → search='release'
- "Next page of branches" → page=2
- Don't use when you want to check if a specific branch exists by exact name —
use gitlab_get_file on that ref and look at the error instead.
Inputs: project_path (required), page, search, per_page. Returns: count, project, branches, pagination
gitlab_list_merge_requestsARead-onlyIdempotent
List merge requests of a project, optionally filtered by state.
Examples:
- "What MRs are open right now" → default (state='opened')
- "What merged last week" → state='merged' then filter by updated_at client-side
- "Everything regardless of state" → state='all'
- Don't use when you have an MR IID — use gitlab_get_merge_request for detail.
Inputs: project_path (required), page, state, per_page. Returns: count, state, project, pagination, +1 more
gitlab_list_pipelinesARead-onlyIdempotent
List recent pipelines of a project, newest first.
Use for triage ("show failed pipelines on master"), release readiness checks, or feeding pipeline IDs into follow-up calls. Read-only and idempotent.
Returns PipelinesListOutput: project, count, pagination and
pipelines[] (each PipelineSummary). The tool result additionally
carries a markdown table in its text content.
Examples:
- "Show failed pipelines on master" → status='failed', ref='master'
- "Last nightly schedule runs" → source='schedule'
- "Second page of pipelines" → page=2
- Don't use when you have a specific pipeline ID — use gitlab_get_pipeline instead.
Inputs: project_path (required), ref, page, source, +2 more. Returns: count, project, pipelines, pagination
gitlab_list_repository_treeARead-onlyIdempotent
List files and directories at a given path in the repository.
Examples:
- "Show top-level files" → default call
- "All .py files recursively" → recursive=True then filter on .py in path
- Don't use for full-text content — use gitlab_get_file for that.
Inputs: project_path (required), ref, page, path, +2 more. Returns: ref, path, count, items, +2 more
gitlab_list_schedulesARead-onlyIdempotent
List all CI/CD schedules of a project.
Variable keys whose name hints at a secret (TOKEN, PASSWORD,
SECRET, CREDENTIAL, PRIVATE_KEY, API_KEY) keep the key
but have the value replaced by *** so the agent still sees which
variables exist.
Examples:
- "What schedules do we have and are they all active" → default call
- Don't use to run a schedule now — use gitlab_trigger_pipeline
with the schedule's variables instead.
Inputs: project_path (required). Returns: project, schedules, active_count, schedules_count
gitlab_list_tagsARead-onlyIdempotent
List tags of a project, newest first.
Useful for release-note generation or checking the last shipped version.
Examples:
- "What was the last release tag" → default call, take the first item
- "All v2.x releases" → search='v2.'
Inputs: project_path (required), page, search, per_page. Returns: tags, count, project, pagination
gitlab_merge_mrADestructiveIdempotent
Perform the actual merge if GitLab reports the MR can be merged.
Destructive: writes to the target branch. Checks merge_status first
and returns status='cannot_merge' if conflicts exist or pipelines are
required.
Examples:
- "Merge !42" → mr_iid=42
- Don't call without checking gitlab_get_merge_request first when you suspect conflicts.
Inputs: mr_iid (required), project_path (required). Returns: iid, hint, state, title, +6 more
gitlab_pipeline_healthARead-onlyIdempotent
Aggregate success rate over 7 and 30 days with a trend indicator.
Great for stand-ups and on-call hand-offs. Returns success rate %, totals,
last-10 statuses and a trend (up/down/flat).
Emits progress via the MCP Context (info log + report_progress) —
useful in IDEs that show per-tool progress bars.
Examples:
- "How stable is master" → default (ref='master', source='schedule')
- "Push-driven pipeline health" → source='push'
- Don't use for a single pipeline — use gitlab_get_pipeline.
Inputs: project_path (required), ref, source. Returns: ref, trend, source, status, +16 more
gitlab_project_infoARead-onlyIdempotent
Return basic metadata about a project: ID, default branch, visibility, counts.
Examples:
- "What's the project ID and default branch" → default call
- "Is this repo public or private" → look at visibility
Inputs: project_path (required). Returns: id, name, web_url, created_at, +7 more
gitlab_retry_pipelineA
Retry all failed jobs of an existing pipeline.
Creates new job runs (new history entries). Safe to call when the pipeline has at least one failed/canceled job; has no effect if everything already passed.
Examples:
- "Retry the failed jobs in pipeline 123" → pipeline_id=123
- Don't use to rerun a successful pipeline — use gitlab_trigger_pipeline instead.
Inputs: pipeline_id (required), project_path (required). Returns: ref, status, web_url, created_at, +2 more
gitlab_trigger_pipelineA
Create a new pipeline on the given ref, optionally with CI variables.
Not idempotent: each call creates a new pipeline. Consumes minutes on your runners — avoid calling in loops.
Examples:
- "Run the pipeline on master" → default (ref='master')
- "Run the pipeline on feature/x with DEBUG=1" → ref='feature/x', variables={'DEBUG': '1'}
- Don't call to retry — use gitlab_retry_pipeline which keeps the same pipeline ID.
Inputs: project_path (required), ref, variables. Returns: ref, status, web_url, created_at, +2 more
gitlab_update_scheduleADestructiveIdempotent
Update an existing schedule. Only provided fields change.
Destructive when variables is set: the entire variable set is replaced,
so ensure the caller sends a full list.
Examples:
- "Deactivate schedule 42" → schedule_id=42, active=False
- "Change cron of schedule 42 to hourly" → schedule_id=42, cron='0 * * * *'
- Don't pass variables unless you want to replace them entirely.
Inputs: schedule_id (required), project_path (required), ref, cron, +3 more. Returns: ref, cron, active, status, +2 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 24 tools
Tools are clearly separated by resource and action: pipeline tools split into list/get/jobs/log/trigger/retry/cancel/health, MR tools into list/get/changes/create/merge, and schedule CRUD is explicit. The only mild overlap is among pipeline-read tools, but the descriptions make boundaries clear.
Most tools follow a predictable gitlab_verb_noun pattern such as gitlab_get_pipeline, gitlab_list_branches, and gitlab_create_schedule. Exceptions include noun-phrase names like gitlab_pipeline_health and gitlab_project_info, the abbreviated gitlab_merge_mr, and the meta gitlab_ci_mcp_check_updates.
At 24 tools the set is on the heavy side, but it covers several distinct areas—pipeline operations, job logs, merge requests, repository browsing, and schedules—and most tools have a clear role. The lone meta update-check tool is slightly out of place but does not dominate the surface.
Core CI lifecycle coverage is strong: pipelines can be listed, inspected, triggered, retried, cancelled, and health-checked, and schedules have full CRUD. However, notable gaps remain: merge requests cannot be updated, closed, commented on, or approved; branches and tags are list-only; and repository file operations are read-only.
Maintenance
Related MCP Connectors
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.
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
GitLab Public MCP — wraps the GitLab REST API v4 (public endpoints, no auth)
Related MCP Servers
- -licenseAqualityBmaintenanceMCP Server for the GitLab API, enabling project management, file operations, and more.95,950 npm91,952MIT
- 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.2,012 npmMIT
- 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
- AlicenseAqualityCmaintenanceMCP server for GitLab REST API enabling AI agents to manage pipelines, merge requests, diffs, and local reviews.159 npmMIT