GitLab集成服务器

GitLab MCP服务器

一个模型上下文协议（MCP）服务器，提供与GitLab的无缝集成，使AI助手能够与GitLab项目、问题、合并请求、CI/CD管道等进行交互。

特性

• 项目管理：列出、创建、更新和删除GitLab项目
• 问题跟踪：问题的完整CRUD操作，包括注释和状态管理
• 合并请求：使用差异查看创建、审核、批准和合并拉取请求
• 存储库操作：分支管理、文件操作、提交和标记
• CI/CD集成：具有日志和重试功能的管道和作业管理
• 组管理：管理GitLab组和组成员资格
• 用户管理：搜索和检索用户信息
• 标签和里程碑：用标签和里程碑组织工作
• 字段过滤：自定义API响应以仅包含所需字段
• 分页支持：高效处理大型结果集
• 全面的错误处理：带有恢复建议的清晰、可操作的错误消息
• SSL验证：自托管实例的可配置SSL证书验证

安装

使用pip安装GitLab MCP服务器：

pip install gitlab-mcp-server

配置

环境变量

服务器需要以下环境变量：

• GITLAB_TOKEN （必填）：您的GitLab个人访问令牌

  • 生成时间：https://gitlab.com/-/profile/personal_access_tokens
  • 所需范围： api, read_user, read_repository, write_repository

• GITLAB_URL （可选）：GitLab实例URL

  • 违约： https://gitlab.com
  • 对于自托管： https://gitlab.example.com

• GITLAB_VERIFY_SSL （可选）：SSL证书验证

  • 违约： true
  • 吃起来 false 用于自签名证书（不建议用于生产）

MCP客户端配置

克劳德桌面

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gitlab": {
      "command": "python",
      "args": ["-m", "gitlab_mcp_server"],
      "env": {
        "GITLAB_TOKEN": "your-personal-access-token",
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_VERIFY_SSL": "true"
      }
    }
  }
}

其他MCP客户端

对于其他MCP兼容客户端，请使用以下命令：

python -m gitlab_mcp_server

在shell中设置环境变量或直接传递：

GITLAB_TOKEN=your-token GITLAB_URL=https://gitlab.com python -m gitlab_mcp_server

可用工具

项目管理

• list_projects：使用分页和搜索列出GitLab项目

  • 参数： per_page, page, search, include_fields

• get_project：获取特定项目的详细信息

  • 参数： project_id, include_fields

• create_project：创建一个新的GitLab项目

  • 参数： name, description, visibility, initialize_with_readme, include_fields

• update_project：更新现有项目

  • 参数： project_id, name, description, visibility, default_branch, include_fields

• delete_project：删除项目

  • 参数： project_id

问题管理

• list_issues：使用筛选列出项目中的问题

  • 参数： project_id, per_page, page, state, labels, include_fields

• get_issue：获取特定问题的详细信息

  • 参数： project_id, issue_iid, include_fields

• create_issue：创建新问题

  • 参数： project_id, title, description, labels, assignee_ids, include_fields

• update_issue：更新现有问题

  • 参数： project_id, issue_iid, title, description, labels, assignee_ids, state_event, include_fields

• close_issue：关闭问题

  • 参数： project_id, issue_iid, include_fields

• reopen_issue：重新打开已关闭的问题

  • 参数： project_id, issue_iid, include_fields

• add_issue_comment：向问题添加评论

  • 参数： project_id, issue_iid, body

• list_issue_comments：列出对某个问题的评论

  • 参数： project_id, issue_iid, per_page, page

合并请求管理

• list_merge_requests：列出项目中的合并请求

  • 参数： project_id, per_page, page, state, include_fields

• get_merge_request：获取特定合并请求的详细信息

  • 参数： project_id, mr_iid, include_fields

• create_merge_request：创建新的合并请求

  • 参数： project_id, source_branch, target_branch, title, description, include_fields

• update_merge_request：更新现有的合并请求

  • 参数： project_id, mr_iid, title, description, target_branch, state_event, include_fields

• merge_merge_request：合并合并请求

  • 参数： project_id, mr_iid, merge_commit_message

• approve_merge_request：批准合并请求

  • 参数： project_id, mr_iid

• get_merge_request_changes：获取合并请求的差异/更改

  • 参数： project_id, mr_iid

• add_merge_request_comment：向合并请求添加注释

  • 参数： project_id, mr_iid, body

• list_merge_request_comments：列出合并请求的注释

  • 参数： project_id, mr_iid, per_page, page

库管理

转移操作

• list_branches：列出存储库中的分支

  • 参数： project_id, per_page, page, search, include_fields

• get_branch：获取特定分支的详细信息

  • 参数： project_id, branch, include_fields

• create_branch：创建新分支

  • 参数： project_id, branch, ref, include_fields

• delete_branch：删除分支

  • 参数： project_id, branch

文件操作

• get_file：从存储库获取文件

  • 参数： project_id, file_path, ref, include_fields

• create_file：在存储库中创建新文件

  • 参数： project_id, file_path, branch, content, commit_message, encoding, include_fields

• update_file：更新现有文件

  • 参数： project_id, file_path, branch, content, commit_message, encoding, include_fields

• delete_file：从存储库中删除文件

  • 参数： project_id, file_path, branch, commit_message

承诺和标签

• list_commits：列出存储库中的提交

  • 参数： project_id, per_page, page, ref_name, include_fields

• get_commit：获取特定提交的详细信息

  • 参数： project_id, sha, include_fields

• list_tags：列出存储库中的标记

  • 参数： project_id, per_page, page, include_fields

• create_tag：创建新标记

  • 参数： project_id, tag_name, ref, message, include_fields

CI/CD管理

管道作业

• list_pipelines：列出CI/CD管道

  • 参数： project_id, per_page, page, ref, status, include_fields

• get_pipeline：获取特定管道的详细信息

  • 参数： project_id, pipeline_id, include_fields

• create_pipeline：触发新管道

  • 参数： project_id, ref, variables, include_fields

• retry_pipeline：重试失败的管道

  • 参数： project_id, pipeline_id

• cancel_pipeline：取消正在运行的管道

  • 参数： project_id, pipeline_id

作业操作

• list_jobs：列出管道中的作业

  • 参数： project_id, pipeline_id, per_page, page, include_fields

• get_job：获取特定工作的详细信息

  • 参数： project_id, job_id, include_fields

• retry_job：重试失败的作业

  • 参数： project_id, job_id

• cancel_job：取消正在运行的作业

  • 参数： project_id, job_id

• get_job_log：获取作业日志

  • 参数： project_id, job_id

组管理

• list_groups：列出GitLab组

  • 参数： per_page, page, search, include_fields

• get_group：获取特定组的详细信息

  • 参数： group_id, include_fields

• create_group：创建新组

  • 参数： name, path, description, visibility, include_fields

• update_group：更新现有组

  • 参数： group_id, name, path, description, visibility, include_fields

• delete_group：删除组

  • 参数： group_id

• list_group_members：列出组的成员

  • 参数： group_id, per_page, page, include_fields

• add_group_member：向组中添加成员

  • 参数： group_id, user_id, access_level, expires_at

用户管理

• get_current_user：获取当前经过身份验证的用户详细信息

  • 参数： include_fields

• get_user：获取特定用户的详细信息

  • 参数： user_id, include_fields

• list_users：列出GitLab用户

  • 参数： per_page, page, include_fields

• search_users：搜索用户

  • 参数： search, per_page, page, include_fields

标签和里程碑管理

标签

• list_labels：列出项目中的标签

  • 参数： project_id, per_page, page, include_fields

• create_label：创建新标签

  • 参数： project_id, name, color, description, include_fields

• update_label：更新现有标签

  • 参数： project_id, label_id, name, color, description, include_fields

• delete_label：删除标签

  • 参数： project_id, label_id

里程碑

• list_milestones：列出项目中的里程碑

  • 参数： project_id, per_page, page, state, include_fields

• create_milestone：创建新的里程碑

  • 参数： project_id, title, description, due_date, start_date, include_fields

• update_milestone：更新现有里程碑

  • 参数： project_id, milestone_id, title, description, due_date, start_date, include_fields

• close_milestone：完成一个里程碑

  • 参数： project_id, milestone_id, include_fields

用法示例

列出项目

# List all accessible projects
list_projects(per_page=20, page=1)

# Search for projects
list_projects(search="my-project")

# Get specific fields only
list_projects(include_fields="id,name,web_url")

创建和管理问题

# Create a new issue
create_issue(
    project_id=123,
    title="Bug: Login not working",
    description="Users cannot log in with valid credentials",
    labels="bug,priority::high"
)

# Add a comment
add_issue_comment(
    project_id=123,
    issue_iid=42,
    body="I've reproduced this issue on staging"
)

# Close the issue
close_issue(project_id=123, issue_iid=42)

创建合并请求

# Create a merge request
create_merge_request(
    project_id=123,
    source_branch="feature/new-login",
    target_branch="main",
    title="Add new login flow",
    description="Implements OAuth2 authentication"
)

# Get the diff
get_merge_request_changes(project_id=123, mr_iid=15)

# Approve and merge
approve_merge_request(project_id=123, mr_iid=15)
merge_merge_request(project_id=123, mr_iid=15)

管理存储库文件

# Get a file
get_file(
    project_id=123,
    file_path="src/main.py",
    ref="main"
)

# Create a new file
create_file(
    project_id=123,
    file_path="docs/api.md",
    branch="main",
    content="# API Documentation\n\n...",
    commit_message="Add API documentation"
)

# Update an existing file
update_file(
    project_id=123,
    file_path="README.md",
    branch="main",
    content="# Updated README\n\n...",
    commit_message="Update README with new instructions"
)

触发和监视CI/CD

# Trigger a pipeline
create_pipeline(
    project_id=123,
    ref="main",
    variables={"DEPLOY_ENV": "staging"}
)

# List pipeline jobs
list_jobs(project_id=123, pipeline_id=456)

# Get job logs
get_job_log(project_id=123, job_id=789)

# Retry a failed job
retry_job(project_id=123, job_id=789)

开发设置

先决条件

• Python 3.10或更高版本
• pip或uv包管理器
• 带有个人访问令牌的GitLab帐户

安装开发

1. 克隆存储库：

git clone https://github.com/yourusername/gitlab-mcp-server.git
cd gitlab-mcp-server

2. 安装依赖项：

pip install -e ".[dev]"

3. 设置环境变量：

export GITLAB_TOKEN="your-personal-access-token"
export GITLAB_URL="https://gitlab.com"

4. 运行测试：

pytest

5. 跑步覆盖：

pytest --cov=gitlab_mcp_server --cov-report=html

6. 运行linting：

pylint src/gitlab_mcp_server

7. 格式代码：

black src/gitlab_mcp_server tests

项目结构

gitlab-mcp-server/
├── src/
│   └── gitlab_mcp_server/
│       ├── __init__.py       # Package initialization
│       ├── server.py          # Main server implementation
│       └── errors.py          # Error handling utilities
├── tests/
│   ├── test_*.py             # Test files
│   └── conftest.py           # Pytest configuration
├── README.md                  # This file
└── pyproject.toml            # Project metadata

贡献

欢迎投稿！请遵循以下指南：

1. 分叉存储库 并创建一个特征分支
2. 编写测试 对于新功能
3. 确保所有测试通过 随着 pytest
4. 遵循代码风格 使用 black 和 pylint
5. 更新文档 对于新功能
6. 提交拉取请求 描述清晰

代码的风格

• 遵循PEP 8指南
• 对函数参数和返回值使用类型提示
• 为所有公共函数和类编写文档字符串
• 保持职能集中，尽可能控制在50行以内
• 使用有意义的变量和函数名

测试

• 为所有新功能编写单元测试
• 保持测试覆盖率在70%以上
• 对外部API调用使用mocking
• 测试错误处理和边缘情况

提交消息

• 使用清晰、描述性的提交消息
• 以动词开头（添加、修复、更新、删除）
• 参考发行号（如适用）

安全

报告安全问题

如果您发现安全漏洞，请发送电子邮件至security@example.com而不是使用问题跟踪器。我们认真对待安全问题，并将迅速作出回应。

安全最佳实践

• 从不提交代币：保持你的 GITLAB_TOKEN 安全，从不将其提交给版本控制
• 使用环境变量：将敏感配置存储在环境变量中
• 启用SSL验证：仅禁用开发/测试的SSL验证
• 定期旋转令牌：定期生成新的个人访问令牌
• 限制令牌范围：仅向您的令牌授予必要的API作用域
• 使用只读令牌：如果可能，请使用具有只读访问权限的令牌

许可证

该项目根据MIT许可证获得许可。有关详细信息，请参阅LICENSE文件。

支持

• 问题：报告错误并请求功能 GitHub问题
• 讨论：就以下内容提问 GitHub讨论
• 文档：API完整文档，网址： docs.example.com

致谢

• 内置于 模型上下文协议
• 用途 httpx 对于HTTP请求
• 受GitLab API和社区的启发

更新日志

看 更改日志.md 查看详细的变化历史。

由以下材料制成❤️ GitLab和AI社区