使用说明
GitLab MCP服务器🦊
GitLab MCP服务器是一个 模型上下文协议（MCP） 服务器，提供与GitLab API的无缝集成，实现高级 GitLab生态系统中开发人员和人工智能工具的自动化和交互功能。
用例✨
- 自动化GitLab工作流和流程（例如，管理问题、合并请求）。
- 从GitLab项目和组中提取和分析数据。
- 构建与GitLab交互的AI驱动工具和应用程序。
先决条件⚙️
- Docker： 要在容器中轻松运行服务器，您需要 码头工人 安装并运行。 （或者，您可以从源代码构建-见下文）。
- GitLab访问令牌： 您需要一个GitLab访问令牌才能使用API进行身份验证。您可以创建：
- A. 个人访问令牌（PAT）
- A. 项目访问令牌
- A. 组访问令牌
所需 范围 取决于您打算使用的工具（例如。，
api作用域授予广泛的访问权限，或选择更细粒度的作用域，如read_repository,write_repository,read_api).只授予你觉得舒服的权限给你的人工智能工具。
安装🚀
使用VS代码（代理模式）
将以下JSON块添加到您的用户设置（JSON）文件中(Preferences: Open User Settings (JSON) 或 Ctrl+Shift+P).这将配置VS Code，使其在激活代理模式时使用Docker运行服务器。
{
"mcp": {
"inputs": [
{
"type": "promptString",
"id": "gitlab_token",
"description": "GitLab Access Token (PAT, Project, or Group)",
"password": true
},
{
"type": "promptString",
"id": "gitlab_host",
"description": "GitLab Host (e.g., gitlab.com or self-managed URL, leave empty for gitlab.com)",
"password": false
}
],
"servers": {
"gitlab": {
// Replace with the actual image path once published (e.g., registry.gitlab.com/your-group/gitlab-mcp-server)
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "GITLAB_TOKEN",
"-e", "GITLAB_HOST",
// IMPORTANT: Update this image path when available!
"your-docker-registry/gitlab-mcp-server:latest"
],
"env": {
"GITLAB_TOKEN": "${input:gitlab_token}",
"GITLAB_HOST": "${input:gitlab_host}"
}
}
}
}
}
（注：更换 "your-docker-registry/gitlab-mcp-server:latest" 一旦实际发布的图像路径可用。)
您还可以添加类似的配置（不包括顶级配置 mcp 键）到a .vscode/mcp.json 您工作区中的文件以共享设置。
更多关于在VS Code中使用MCP服务器工具的信息 代理模式文档.
使用Claude Desktop
（示例结构，根据需要适应Claude Desktop配置）
{
"mcpServers": {
"gitlab": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "GITLAB_TOKEN=<YOUR_TOKEN>",
"-e", "GITLAB_HOST=<YOUR_GITLAB_URL_OR_EMPTY>",
// IMPORTANT: Update this image path when available!
"your-docker-registry/gitlab-mcp-server:latest"
]
// Alternatively use env block if Claude supports it:
// "env": {
// "GITLAB_TOKEN": "<YOUR_TOKEN>",
// "GITLAB_HOST": "<YOUR_GITLAB_URL_OR_EMPTY>"
// }
}
}
}
从源代码构建
如果你不想使用Docker，你可以直接构建二进制文件：
- 克隆存储库。
- 导航到存储库根目录。
- 构建服务器：
go build -o gitlab-mcp-server ./cmd/gitlab-mcp-server - 配置您的MCP客户端（例如，VS代码用户设置JSON）以使用构建的可执行文件：
// Example for VS Code User Settings (JSON)
{
"mcp": {
"servers": {
"gitlab": {
"command": "/path/to/your/gitlab-mcp-server", // Replace with actual path
"args": ["stdio"],
"env": {
"GITLAB_TOKEN": "<YOUR_TOKEN>",
"GITLAB_HOST": "<YOUR_GITLAB_URL_OR_EMPTY>"
}
}
}
}
}
工具配置🛠️
GitLab MCP服务器支持通过以下方式启用或禁用特定功能组（工具集） --toolsets 旗帜或 GITLAB_TOOLSETS 环境变量。这允许对暴露于人工智能工具的GitLab API功能进行细粒度控制。仅启用必要的工具集可以改进LLM工具选择并减小上下文大小。
可用工具集
计划使用以下工具集（如果 GITLAB_TOOLSETS 未设置或设置为 "all"):
| 工具集 | 说明 |
|---|---|
projects |
项目详细信息、存储库操作（文件、分支、提交、标签）。 |
issues |
问题管理（CRUD、注释、标签、里程碑）。 |
merge_requests |
合并请求操作（CRUD、注释、批准、差异、状态检查）。 |
security |
访问安全扫描结果（SAST、秘密检测等）。 |
users |
用户信息查找，可能是当前用户详细信息。 |
search |
利用GitLab的范围搜索功能（项目、问题、MR、代码）。 |
（潜在未来： ci_cd, groups, epics) |
指定工具集
传递所需工具集的允许列表（逗号分隔）：
-
使用命令行参数 （直接运行二进制文件时）：
./gitlab-mcp-server stdio --toolsets issues,merge_requests,projects -
使用环境变量:
export GITLAB_TOOLSETS="issues,merge_requests,projects" ./gitlab-mcp-server stdio（环境变量
GITLAB_TOOLSETS优先于国旗。)
在Docker中使用工具集
运行容器时通过环境变量传递工具集：
docker run -i --rm \
-e GITLAB_TOKEN=<your-token> \
-e GITLAB_HOST=<your-gitlab-url_or_empty> \
-e GITLAB_TOOLSETS="issues,merge_requests,projects" \
your-docker-registry/gitlab-mcp-server:latest # IMPORTANT: Update image path!
“全部”工具集
使用特殊值 all 要明确启用所有可用的工具集：
./gitlab-mcp-server stdio --toolsets all
# or
export GITLAB_TOOLSETS="all"
./gitlab-mcp-server stdio
# or with Docker
docker run -i --rm -e GITLAB_TOKEN=... -e GITLAB_TOOLSETS="all" ...
动态工具发现💡
（此功能可能稍后实现，遵循github mcp服务器的模式）
动态工具集发现允许MCP主机（如VS Code或Claude）列出可用的工具集，并根据用户需求选择性地启用它们，而不是从一组固定的已启用工具开始。这可以防止最初用太多的工具压倒语言模型。
使用动态工具发现
如果已实施，请通过以下方式启用：
- 标志：
./gitlab-mcp-server stdio --dynamic-toolsets - 环境变量：
export GITLAB_DYNAMIC_TOOLSETS=1 - Docker：
docker run -i --rm -e GITLAB_TOKEN=... -e GITLAB_DYNAMIC_TOOLSETS=1 ...
启用后，服务器最初只公开最小的工具，包括动态列出和启用其他工具集的工具。
GitLab自管理实例🏢
连接到自我管理的GitLab实例，而不是 gitlab.com，使用 --gitlab-host 旗帜或 GITLAB_HOST 环境变量。提供实例的基本URL（例如。， https://gitlab.example.com).
- 标志：
./gitlab-mcp-server stdio --gitlab-host https://gitlab.example.com - 环境变量：
export GITLAB_HOST="https://gitlab.example.com" - Docker：
docker run -i --rm -e GITLAB_TOKEN=... -e GITLAB_HOST="https://gitlab.example.com" ...
如果变量/标志为空或省略，服务器默认为 https://gitlab.com.
i18n/覆盖性描述🌍
工具名称和描述可以定制或翻译。创建一个 gitlab-mcp-server-config.json 文件在 同一目录 作为服务器二进制文件（或将其装载到容器中）。
该文件应包含一个JSON对象，将内部转换键（对应于工具名称/描述）映射到所需的字符串。
示例 gitlab-mcp-server-config.json:
{
"TOOL_GET_ISSUE_DESCRIPTION": "Fetch details for a specific GitLab issue.",
"TOOL_CREATE_MERGE_REQUEST_USER_TITLE": "Open New MR"
}
您可以通过使用以下命令运行服务器来生成包含所有当前翻译密钥的模板文件 --export-translations 标志：
./gitlab-mcp-server --export-translations
# This will create/update gitlab-mcp-server-config.json
此标志在添加服务器中引入的任何新密钥时保留现有的覆盖。
贡献和许可🤝
欢迎投稿！请看 贡献.md 了解详情。
该项目发布于 MIT许可证.
