内容
# gitlab-mcp
一款适用于当前 [GitLab REST API v4](https://docs.gitlab.com/api/rest/) 的 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器，使用 Go 语言编写，并使用官方的 [`github.com/modelcontextprotocol/go-sdk`](https://github.com/modelcontextprotocol/go-sdk)。
它支持 GitLab.com 和 GitLab 自管理实例，支持标准输入输出和可流式传输的 HTTP 协议，支持分页结果，并具有独立的 `readonly` 和 `readwrite` 模式。默认模式为 `readonly`。
## 快速入门
创建 GitLab 个人、项目或组访问令牌，然后运行：
```bash
export GITLAB_TOKEN=glpat-your-token
go run ./cmd/gitlab-mcp --mode=readonly --transport=stdio
```
对于自管理实例：
```bash
export GITLAB_BASE_URL=https://gitlab.example.com
export GITLAB_TOKEN=glpat-your-token
go run ./cmd/gitlab-mcp
```
`GITLAB_BASE_URL` 是实例 URL，不包括 `/api/v4`；服务器会自动追加稳定的 GitLab REST API 路径。
## 配置
命令行标志覆盖环境变量。
| 环境变量 | 命令行标志 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `GITLAB_BASE_URL` | `--gitlab-base-url` | `https://gitlab.com` | GitLab 实例 URL |
| `GITLAB_TOKEN` | `--gitlab-token` | 必需 | 个人、项目或组访问令牌 |
| `GITLAB_MODE` | `--mode` | `readonly` | `readonly` 或 `readwrite` |
| `MCP_TRANSPORT` | `--transport` | `stdio` | `stdio` 或 `http` |
| `MCP_HTTP_ADDR` | `--http-addr` | `:8080` | HTTP 监听地址 |
| `MCP_AUTH_TOKEN` | `--auth-token` | 空 | HTTP MCP 客户端所需的 Bearer 令牌 |
运行 `gitlab-mcp --version` 以打印构建版本。
## 工具
项目参数接受数字项目 ID 或未转义的全路径，例如 `group/subgroup/project`。
### 只读工具
| 工具 | 目的 |
| --- | --- |
| `gitlab_get_metadata` | 获取连接的 GitLab 版本和实例元数据 |
| `gitlab_get_current_user` | 获取由配置令牌表示的用户 |
| `gitlab_list_projects` | 列出和过滤可见项目 |
| `gitlab_get_project` | 按 ID 或路径获取项目 |
| `gitlab_list_issues` | 列出项目或跨项目的问题 |
| `gitlab_get_issue` | 按项目和 IID 获取问题 |
| `gitlab_list_issue_notes` | 列出问题评论和系统注释 |
| `gitlab_list_merge_requests` | 列出项目或跨项目的合并请求 |
| `gitlab_get_merge_request` | 按项目和 IID 获取合并请求 |
| `gitlab_list_merge_request_notes` | 列出合并请求注释 |
| `gitlab_list_repository_tree` | 浏览仓库树 |
| `gitlab_get_file` | 读取和解码仓库文件在引用处 |
| `gitlab_list_branches` | 列出仓库分支 |
| `gitlab_list_commits` | 列出仓库提交 |
| `gitlab_get_commit` | 获取一个提交 |
| `gitlab_list_pipelines` | 列出项目管道 |
| `gitlab_get_pipeline` | 获取一个管道 |
| `gitlab_list_pipeline_jobs` | 列出管道中的作业 |
| `gitlab_search` | 在全局、组或项目中搜索 |
### 写工具
这些工具仅在设置 `GITLAB_MODE=readwrite` 或 `--mode=readwrite` 时注册。
| 工具 | 目的 |
| --- | --- |
| `gitlab_create_issue` | 创建问题 |
| `gitlab_update_issue` | 更新、关闭或重新打开问题 |
| `gitlab_add_issue_note` | 添加问题注释 |
| `gitlab_create_merge_request` | 创建合并请求 |
| `gitlab_update_merge_request` | 更新、关闭或重新打开合并请求 |
| `gitlab_add_merge_request_note` | 添加合并请求注释 |
| `gitlab_accept_merge_request` | 现在或在管道成功后合并 |
| `gitlab_create_branch` | 从引用创建分支 |
| `gitlab_create_commit` | 提交一批文件创建/更新/移动/删除/chmod 操作 |
| `gitlab_create_pipeline` | 运行管道，可选地带有变量和类型化输入 |
| `gitlab_retry_pipeline` | 重试失败或取消的管道作业 |
问题和合并请求的描述和注释直接使用 GitLab 风格的 Markdown。仓库文件响应限制为 25 MiB。暂时的 `429`、`502`、`503` 和 `504` 响应最多重试三次，遵守 `Retry-After`。
## 认证和令牌范围
服务器在 GitLab 推荐的 `PRIVATE-TOKEN` 头中发送配置的令牌。使用最窄的令牌和项目成员身份来支持您启用的工具：
- `readonly`：使用 `read_api`；当需要仓库内容并且令牌类型支持该范围时，请添加 `read_repository`。
- `readwrite`：使用 `api`，因为问题、合并请求、仓库和管道写入需要 API 写访问。
GitLab 授权仍然适用于每个请求。令牌无法访问或修改其用户、项目或组成员身份无法访问的资源。
## 传输
### 标准输入输出
```bash
gitlab-mcp --transport=stdio
```
### 可流式传输的 HTTP
```bash
gitlab-mcp --transport=http --http-addr=127.0.0.1:8080 \
--auth-token=choose-a-separate-mcp-token
```
HTTP 客户端必须发送 `Authorization: Bearer <mcp-token>`。此令牌保护 MCP 端点，与 `GITLAB_TOKEN` 分开。如果未配置 MCP 身份验证令牌，则 HTTP 端点没有应用级身份验证。当与 `readwrite` 模式结合使用时，服务器会记录警告。
## MCP 客户端配置
Claude Desktop：
```json
{
"mcpServers": {
"gitlab": {
"command": "gitlab-mcp",
"args": [],
"env": {
"GITLAB_BASE_URL": "https://gitlab.com",
"GITLAB_TOKEN": "glpat-your-token",
"GITLAB_MODE": "readonly"
}
}
}
}
```
VS Code `.vscode/mcp.json`：
```json
{
"servers": {
"gitlab": {
"command": "gitlab-mcp",
"args": [],
"env": {
"GITLAB_BASE_URL": "https://gitlab.com",
"GITLAB_TOKEN": "glpat-your-token",
"GITLAB_MODE": "readonly"
}
}
}
}
```
## 开发
需要 Go 1.26 或更新版本。
```bash
go build ./...
go test ./...
go vet ./...
```
测试涵盖配置、身份验证、项目路径和文件路径编码、分页、API 错误、重试处理、文件解码、提交有效负载、工具模式门控以及端到端标准输入输出和 HTTP MCP 连接。
## 许可证
MIT。参见 [LICENSE](LICENSE)。
