MCP Gitlab

🚀 MCP GitLab 服务器

MCP GitLab 服务器是一个基于模型上下文协议（MCP）的服务器，它提供了全面的 GitLab API 集成。该服务器使大语言模型（LLMs）能够与 GitLab 仓库进行交互，管理合并请求、问题，并执行各种 Git 操作。

🚀 快速开始

本服务器提供了便捷的使用方式，让你可以轻松开启与 GitLab 的交互之旅。以下为你介绍不同的启动途径：

使用 uvx（推荐 - 无需安装）

# 无需安装，直接运行
uvx mcp-gitlab

从源代码安装

# 克隆仓库
git clone https://github.com/Vijay-Duke/mcp-gitlab.git
cd mcp-gitlab

# 安装依赖并使用 uv 运行
uv sync
uv run mcp-gitlab

# 或者以开发模式安装并包含测试依赖
uv sync --all-extras
uv run pytest  # 运行测试

✨ 主要特性

核心特性

• 🔐 认证与用户：获取当前用户信息并查找用户资料。
• 🔍 项目管理：列出、搜索并获取 GitLab 项目的详细信息。
• 📝 问题管理：列出、读取、搜索问题并发表评论。
• 🔀 合并请求管理：列出、读取、更新、批准和合并合并请求。
• 📁 仓库文件操作：浏览、读取文件并提交文件更改。
• 🌳 分支与标签管理：列出并管理分支和标签。
• 🔧 CI/CD 管道管理：查看管道状态、作业和工件。
• 💬 讨论管理：读取并解决合并请求讨论。
• 🎯 智能操作：支持批量操作、AI 摘要和智能差异比较。

高级特性

• 批量操作：原子性地执行多个 GitLab 操作，并支持回滚。
• AI 优化摘要：生成合并请求、问题和管道的简洁摘要。
• 智能差异比较：获取结构化的差异比较结果，并可配置上下文和大小限制。
• 安全预览：在提交前预览文件更改。
• 交叉引用支持：在批量模式下引用先前操作的结果。

📦 安装指南

使用 uvx（推荐 - 无需安装）

# 直接运行，无需安装
uvx mcp-gitlab

从源代码安装

# 克隆仓库
git clone https://github.com/Vijay-Duke/mcp-gitlab.git
cd mcp-gitlab

# 安装依赖并使用 uv 运行
uv sync
uv run mcp-gitlab

# 或者以开发模式安装并包含测试依赖
uv sync --all-extras
uv run pytest  # 运行测试

💻 使用示例

基础用法

# 自动检测并列出问题
# 首先从 git 仓库获取当前项目
project = await session.call_tool("gitlab_get_current_project")

# 然后列出未解决的问题
issues = await session.call_tool("gitlab_list_issues", {
    "state": "opened"
})

高级用法

# 使用批量操作创建修复
# 原子性操作：获取问题 → 创建分支 → 提交修复 → 创建合并请求
result = await session.call_tool("gitlab_batch_operations", {
    "operations": [
        {
            "name": "issue",
            "tool": "gitlab_get_issue", 
            "arguments": {"issue_iid": 123}
        },
        {
            "name": "fix",
            "tool": "gitlab_create_commit",
            "arguments": {
                "branch": "fix-issue-{{issue.iid}}",
                "commit_message": "Fix: {{issue.title}}",
                "actions": [{
                    "action": "update",
                    "file_path": "src/bug.py",
                    "content": "# Fixed code here"
                }]
            }
        },
        {
            "name": "mr",
            "tool": "gitlab_create_merge_request",
            "arguments": {
                "source_branch": "fix-issue-{{issue.iid}}",
                "target_branch": "main",
                "title": "Fix: {{issue.title}}",
                "description": "Fixes #{{issue.iid}}"
            }
        }
    ]
})

📚 详细文档

可用工具

认证与用户信息

• gitlab_get_current_user：获取当前认证用户的个人资料信息。

{}

返回的综合信息包括：

• 基本信息：ID、用户名、姓名、电子邮件。

• 个人资料详情：简介、组织、职位。

• 账户状态：状态、创建日期、管理员状态。

• 权限：是否可以创建组、是否可以创建项目。

• 安全信息：是否启用双因素认证、外部状态。

• gitlab_get_user：按 ID 或用户名获取特定用户的详细信息。

{
  "user_id": 12345
}

或

{
  "username": "johndoe"
}

返回的用户信息包括：

• 基本信息：ID、用户名、姓名。
• 个人资料：头像 URL、网页 URL、简介。
• 组织详情：公司、职位。
• 账户状态和创建日期。

项目管理

• gitlab_list_projects：列出可访问的 GitLab 项目，并支持分页和搜索。

{
  "owned": false,
  "search": "my-project",
  "per_page": 20,
  "page": 1
}

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

{
  "project_id": "group/project"
}

• gitlab_get_current_project：从当前的 git 仓库获取 GitLab 项目信息。

{
  "path": "."
}

问题管理

• gitlab_list_issues：列出项目问题，并支持状态过滤。

{
  "project_id": "group/project",
  "state": "opened",
  "per_page": 20
}

• gitlab_get_issue：获取单个问题的完整详细信息。

{
  "project_id": "group/project",
  "issue_iid": 123
}

• gitlab_add_issue_comment：为问题添加评论。

{
  "project_id": "group/project",
  "issue_iid": 123,
  "body": "Thanks for reporting this!"
}

合并请求管理

• gitlab_list_merge_requests：列出合并请求，并支持过滤选项。

{
  "project_id": "group/project",
  "state": "opened"
}

• gitlab_get_merge_request：获取合并请求的详细信息。

{
  "project_id": "group/project",
  "mr_iid": 456
}

• gitlab_update_merge_request：更新合并请求的字段。

{
  "project_id": "group/project",
  "mr_iid": 456,
  "title": "Updated title",
  "description": "New description",
  "labels": "bug,priority"
}

• gitlab_merge_merge_request：合并合并请求，并支持选项设置。

{
  "project_id": "group/project",
  "mr_iid": 456,
  "squash": true,
  "should_remove_source_branch": true
}

• gitlab_approve_merge_request：批准合并请求。

{
  "project_id": "group/project",
  "mr_iid": 456
}

仓库操作

• gitlab_get_file_content：从仓库读取文件内容。

{
  "project_id": "group/project",
  "file_path": "src/main.py",
  "ref": "main"
}

• gitlab_create_commit：创建包含多个文件更改的提交。

{
  "project_id": "group/project",
  "branch": "feature-branch",
  "commit_message": "Add new features",
  "actions": [
    {
      "action": "create",
      "file_path": "new_file.py",
      "content": "print('Hello')"
    },
    {
      "action": "update",
      "file_path": "existing.py",
      "content": "# Updated content"
    }
  ]
}

• gitlab_compare_refs：比较两个分支、标签或提交。

{
  "project_id": "group/project",
  "from_ref": "main",
  "to_ref": "feature-branch"
}

CI/CD 作业和工件

• gitlab_list_pipeline_jobs：列出特定 CI/CD 管道中的作业。

{
  "project_id": "group/project",
  "pipeline_id": 789,
  "per_page": 20,
  "page": 1
}

• gitlab_list_project_jobs：列出项目的作业，并支持可选的范围过滤。

{
  "project_id": "group/project",
  "scope": "failed",
  "per_page": 25
}

• gitlab_download_job_artifact：获取作业工件的信息（安全说明：内容不会下载）。

{
  "project_id": "group/project",
  "job_id": 456,
  "artifact_path": "build.zip"
}

高级工具

• gitlab_batch_operations：原子性地执行多个操作，并支持回滚。

{
  "project_id": "group/project",
  "operations": [
    {
      "name": "get_issue",
      "tool": "gitlab_get_issue",
      "arguments": {"issue_iid": 123}
    },
    {
      "name": "create_mr",
      "tool": "gitlab_create_merge_request",
      "arguments": {
        "source_branch": "fix-{{get_issue.iid}}",
        "target_branch": "main",
        "title": "Fix: {{get_issue.title}}"
      }
    }
  ]
}

• gitlab_summarize_merge_request：生成合并请求的 AI 友好摘要。

{
  "project_id": "group/project",
  "mr_iid": 456,
  "max_length": 500
}

• gitlab_smart_diff：获取结构化的差异比较结果，并可配置上下文和大小限制。

{
  "project_id": "group/project",
  "from_ref": "main",
  "to_ref": "feature",
  "context_lines": 3,
  "max_file_size": 50000
}

用户与个人资料管理

• gitlab_search_user：按姓名、用户名或电子邮件搜索 GitLab 用户。

{
  "search": "John",
  "per_page": 10
}

• gitlab_get_user_details：获取全面的用户个人资料和元数据。

{
  "username": "johndoe"
}

• gitlab_get_my_profile：获取当前认证用户的完整个人资料。

{}

• gitlab_get_user_contributions_summary：总结用户在问题、合并请求和提交方面的近期贡献。

{
  "username": "johndoe",
  "since": "2024-01-01",
  "until": "2024-01-31"
}

• gitlab_get_user_activity_feed：检索用户的完整活动/事件时间线。

{
  "username": "johndoe", 
  "target_type": "Issue",
  "after": "2024-01-01"
}

用户的问题与合并请求

• gitlab_get_user_open_mrs：获取用户发起的所有未处理合并请求。

{
  "username": "johndoe",
  "sort": "updated"
}

• gitlab_get_user_review_requests：获取用户被指定为审核人且有待处理操作的合并请求。

{
  "username": "johndoe",
  "priority": "high",
  "sort": "urgency"
}

• gitlab_get_user_open_issues：获取分配给用户的未处理问题，并按严重程度/SLA 排序。

{
  "username": "johndoe",
  "sla_status": "overdue",
  "sort": "priority"
}

• gitlab_get_user_reported_issues：获取用户报告/创建的问题。

{
  "username": "johndoe",
  "state": "opened",
  "since": "2024-01-01"
}

• gitlab_get_user_resolved_issues：获取用户关闭/解决的问题。

{
  "username": "johndoe",
  "since": "2024-01-01",
  "until": "2024-03-31"
}

用户的代码与提交

• gitlab_get_user_commits：获取用户在指定日期范围或分支内的提交。

{
  "username": "johndoe", 
  "branch": "main",
  "since": "2024-01-01",
  "include_stats": true
}

完整工具列表

• 项目管理：gitlab_list_projects、gitlab_get_project、gitlab_get_current_project、gitlab_search_projects
• 问题管理：gitlab_list_issues、gitlab_get_issue、gitlab_add_issue_comment、gitlab_summarize_issue
• 合并请求管理：gitlab_list_merge_requests、gitlab_get_merge_request、gitlab_update_merge_request、gitlab_close_merge_request、gitlab_merge_merge_request、gitlab_add_merge_request_comment、gitlab_get_merge_request_notes、gitlab_approve_merge_request、gitlab_get_merge_request_approvals、gitlab_get_merge_request_discussions、gitlab_resolve_discussion、gitlab_get_merge_request_changes、gitlab_rebase_merge_request
• 仓库管理：gitlab_get_file_content、gitlab_list_repository_tree、gitlab_list_commits、gitlab_get_commit、gitlab_get_commit_diff、gitlab_create_commit、gitlab_cherry_pick_commit、gitlab_compare_refs、gitlab_list_tags
• 分支管理：gitlab_list_branches
• 管道与作业管理：gitlab_list_pipelines、gitlab_list_pipeline_jobs、gitlab_list_project_jobs、gitlab_download_job_artifact、gitlab_summarize_pipeline
• 搜索功能：gitlab_search_projects、gitlab_search_in_project
• 用户管理：gitlab_get_current_user、gitlab_get_user、gitlab_list_user_events、gitlab_list_project_members
• 用户与个人资料管理：gitlab_search_user、gitlab_get_user_details、gitlab_get_my_profile、gitlab_get_user_contributions_summary、gitlab_get_user_activity_feed
• 用户的问题与合并请求管理：gitlab_get_user_open_mrs、gitlab_get_user_review_requests、gitlab_get_user_open_issues、gitlab_get_user_reported_issues、gitlab_get_user_resolved_issues
• 用户的代码与提交管理：gitlab_get_user_commits
• 版本发布管理：gitlab_list_releases
• Webhook 管理：gitlab_list_project_hooks
• AI 工具：gitlab_summarize_merge_request、gitlab_summarize_issue、gitlab_summarize_pipeline
• 高级工具：gitlab_batch_operations、gitlab_smart_diff、gitlab_safe_preview_commit

配置

环境变量

设置以下认证令牌之一：

# 私有令牌（个人使用推荐）
export GITLAB_PRIVATE_TOKEN="your-private-token"

# OAuth 令牌
export GITLAB_OAUTH_TOKEN="your-oauth-token"

# GitLab URL（可选，默认为 https://gitlab.com）
export GITLAB_URL="https://gitlab.example.com"

获取 GitLab 令牌

1. 进入你的 GitLab 个人资料设置。
2. 导航到“访问令牌”。
3. 创建一个具有以下作用域的新令牌：
   • api - 完整的 API 访问权限。
   • read_repository - 读取仓库内容。
   • write_repository - 写入仓库内容（用于提交）。

使用方法

与 Claude Desktop 配合使用

添加到你的 Claude Desktop 配置中：

使用 uvx（推荐 - 无需安装）

{
  "mcp-gitlab": {
    "command": "uvx",
    "args": ["mcp-gitlab"],
    "env": {
      "GITLAB_PRIVATE_TOKEN": "your-token-here"
    }
  }
}

使用 uv（如果你克隆了仓库）

{
  "mcp-gitlab": {
    "command": "uv",
    "args": ["run", "mcp-gitlab"],
    "cwd": "/path/to/mcp-gitlab",
    "env": {
      "GITLAB_PRIVATE_TOKEN": "your-token-here"
    }
  }
}

将 /path/to/mcp-gitlab 替换为你克隆仓库的完整路径。

使用 uvx 运行

# 设置你的 GitLab 令牌
export GITLAB_PRIVATE_TOKEN="your-token-here"

# 使用 uvx 直接运行服务器
uvx mcp-gitlab

独立使用

# 如果从源代码运行（在 uv sync 之后）
uv run mcp-gitlab

# 或者直接运行 Python 模块
uv run python -m mcp_gitlab

🔧 技术细节

开发

快速开始

# 安装开发依赖
make install-dev

# 在本地运行所有检查
make ci-local

# 格式化代码
make format

# 运行带覆盖率的测试
make test-cov

CI/CD 管道

本项目使用 GitHub Actions 进行持续集成和部署：

• CI 管道：每次推送和 PR 时运行

  • 代码检查（Ruff、Black、isort、MyPy）
  • 测试（pytest 并带覆盖率）
  • 安全扫描（Bandit、Safety、pip-audit）
  • 多版本 Python 测试（3.10、3.11、3.12）

• 代码质量：

  • SonarCloud 分析
  • CodeQL 安全分析
  • 复杂度指标（Radon、Xenon）

• 发布管道：在版本标签上自动发布

  • PyPI 包发布
  • Docker 镜像构建和发布
  • GitHub 版本发布

运行测试

# 运行所有测试
uv run pytest tests/ -v

# 运行带覆盖率的测试
uv run pytest tests/ --cov=mcp_gitlab

# 运行特定的测试文件
uv run pytest tests/test_gitlab_client.py -v

代码风格

项目使用以下工具进行代码风格管理：

• Black 用于代码格式化
• isort 用于导入排序
• flake8 用于代码检查
• mypy 用于类型检查

# 格式化代码
black src/ tests/
isort src/ tests/

# 运行代码检查工具
flake8 src/ tests/
mypy src/

故障排除

认证问题

• 确保你的令牌具有所需的作用域（api、read_repository、write_repository）。
• 检查令牌的过期日期。
• 如果你使用的是自托管实例，请验证 GitLab URL。

速率限制

GitLab API 有速率限制。服务器会优雅地处理速率限制错误，并返回适当的错误消息。

大响应

如果响应超过大小限制，会自动截断。使用分页参数分块检索数据。

贡献

1. 分叉仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交你的更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打开拉取请求

📄 许可证

本项目采用 Apache 许可证 2.0 版 - 有关详细信息，请参阅 LICENSE 文件。

致谢

• 基于 模型上下文协议 构建。
• 使用 python-gitlab 进行 GitLab API 交互。
• 受改善大语言模型与 GitLab 集成需求的启发。