gitlab-mcp-legacy

面向 GitLab 11.11.8 的 GitLab MCP 兼容分支，主要服务仓库阅读、Merge Request 审查和 pipeline/job 排查。 基于 zereight/gitlab-mcp v2.3.19，本分支初始版本为 0.1.0。

A GitLab MCP fork for core repository, merge-request and pipeline workflows on legacy GitLab 11.11.8.

GitHub · npm · GitLab 11.11 兼容说明

快速开始：本地 stdio，只读

使用 Node.js 22.23.4；本地开发使用 npm 和仓库中的 package-lock.json。 以下配置通过 npx -y gitlab-mcp-legacy@0.1.1 启动固定版本。 运行 MCP 客户端的环境需要能够找到 npx，首次启动需要能够访问 npm registry。

1. 准备本地 Token 文件

GitLab 11.11 的个人访问 Token 使用 api scope；该版本尚无后续版本的 read_api scope。 请使用仅能访问所需项目的账号，并在 MCP 服务端显式启用 readonly。

用本地编辑器将 PAT 作为唯一内容保存到自己管理的文件，例如 /absolute/path/to/gitlab-token，然后设置权限：

chmod 600 /absolute/path/to/gitlab-token

配置中只保存文件的绝对路径。Token 文件放在仓库外，父目录建议仅允许当前用户访问。 使用文件模式时，启动环境应只提供 Token 文件路径；已有的内联 Token 设置会优先于文件。 服务端在启动时读取文件，轮换 Token 后需要重启 MCP 进程。

2. 配置 Codex

将以下内容加入 Codex 的 config.toml，替换示例域名和 Token 文件路径。 完整示例见 examples/codex-readonly.toml。

# Replace the example API URL and absolute token-file path before use.
[mcp_servers.gitlab_legacy]
command = "npx"
args = ["-y", "gitlab-mcp-legacy@0.1.1"]
enabled = true
default_tools_approval_mode = "writes"
enabled_tools = [
  "health_check",
  "search_repositories",
  "list_projects",
  "get_project",
  "get_repository_tree",
  "get_file_contents",
  "list_commits",
  "get_commit",
  "list_branches",
  "get_branch",
  "list_tags",
  "get_tag",
  "list_merge_requests",
  "get_merge_request",
  "get_merge_request_diffs",
  "list_merge_request_changed_files",
  "list_merge_request_diffs",
  "get_merge_request_file_diff",
  "list_merge_request_versions",
  "get_merge_request_version",
  "mr_discussions",
  "list_merge_request_pipelines",
  "list_pipelines",
  "get_pipeline",
  "list_pipeline_jobs",
  "get_pipeline_job",
  "get_pipeline_job_output",
  "list_pipeline_schedules",
]

[mcp_servers.gitlab_legacy.env]
GITLAB_API_URL = "https://gitlab.example.com/api/v4"
GITLAB_PERSONAL_ACCESS_TOKEN_FILE = "/absolute/path/to/gitlab-token"
GITLAB_IS_OLD = "true"
GITLAB_PERMISSION_MODE = "readonly"
GITLAB_TOOLSETS = "repositories"
GITLAB_TOOLS = "health_check,search_repositories,list_projects,get_project,get_repository_tree,get_file_contents,list_commits,get_commit,list_branches,get_branch,list_tags,get_tag,list_merge_requests,get_merge_request,get_merge_request_diffs,list_merge_request_changed_files,list_merge_request_diffs,get_merge_request_file_diff,list_merge_request_versions,get_merge_request_version,mr_discussions,list_merge_request_pipelines,list_pipelines,get_pipeline,list_pipeline_jobs,get_pipeline_job,get_pipeline_job_output,list_pipeline_schedules"
GITLAB_DENIED_TOOLS_REGEX = "^(discover_tools|help)$"
GITLAB_DISABLE_VERSION_CHECK = "true"

这份配置组合服务端的工具集合、显式工具列表和拒绝正则，并在客户端重复设置 28 项白名单。 GITLAB_IS_OLD=true 使用旧实例需要的 Private-Token 请求头。 GITLAB_DISABLE_VERSION_CHECK=true 关闭包版本更新检查。

源码的权限模式默认是 full。只读使用必须显式设置 GITLAB_PERMISSION_MODE=readonly，并保留上述工具筛选配置。 GitLab PAT 本身仍可能拥有写权限；客户端白名单不能代替服务端权限控制。

3. 检查连接并读取项目

重启或重新连接 MCP 后，先调用 health_check，再使用 list_projects 或 search_repositories 查找项目。 常见流程：

• 仓库：get_project → get_repository_tree → get_file_contents。

• 提交与分支：list_commits / get_commit、list_branches / get_branch、list_tags / get_tag。

• MR 审查：list_merge_requests → get_merge_request → list_merge_request_changed_files → get_merge_request_file_diff；讨论使用 mr_discussions。

• CI 排查：list_pipelines → get_pipeline → list_pipeline_jobs → get_pipeline_job_output。

project_id 可使用数字 ID 或 URL 编码路径，例如 group%2Fproject；merge_request_iid 是项目内的 MR 编号。

Related MCP server: GitLab MCP Server

兼容与验证边界

真实只读验证使用 GitLab 11.11.8，覆盖 two projects：

MR 关联 pipeline 列表和 pipeline schedule 列表的真实返回均为空，非空数据仍需验证。 所有真实写能力均未验证；本地 mock 对写请求的检查不能代替真实 GitLab 验收。

兼容处理包括旧响应中缺失字段、repository tree 的 offset 分页，以及旧版 MR diff 的 /changes 路由。 MR diff 的分页和文件筛选在本地完成，服务端仍会读取完整的旧版 changes 响应，大型 MR 需要留意响应体积。 已识别的旧版缺失 API 能力和不支持参数会按兼容规则拒绝，具体见兼容说明。

源码继承了上游的 288 项工具实现。当前真实验证集中于上述 28 项只读工具，不能据此推断全部工具兼容 GitLab 11。 其他 GitLab 版本、许可证、权限设置和部署环境需要分别验证；启用写操作前应先在专用测试项目验收。

本地开发与验证

先切换到 .nvmrc 指定的 Node.js 22.23.4，再按 npm 锁文件安装：

git clone https://github.com/x1nfinity/gitlab-mcp-legacy.git
cd gitlab-mcp-legacy
npm ci --ignore-scripts
npm run build
node --import tsx/esm --test --test-concurrency=1 \
  test/gitlab-11-response-schema.test.ts test/test-gitlab-11-core.ts

上述测试使用合成的 GitLab 11.11.8 响应与本地 HTTP mock，通过 MCP stdio 调用构建后的服务端。 测试验证旧版路由、参数转换与拒绝行为，并覆盖部分现代实例路由保持情况。 真实实例验证需要自行准备目标实例、Token、项目与对应数据。

进阶参考与上游归属

• GitLab 11.11 兼容说明：响应差异、受限能力与回归验证方式。

• 工具参考和环境变量参考：继承的进阶功能说明；工具可用性以本分支兼容说明和实际验证为准。

• 上游项目：本分支基于 v2.3.19 维护，安装本分支使用 npm 包 gitlab-mcp-legacy。

项目使用 MIT License，保留原始版权声明 Copyright (c) 2025-2026 zereight。