GitLab API集成服务器（Vijay-Duke） - MCP Server 功能介绍与安装配置

Name: GitLab API集成服务器
Author: Vijay-Duke

使用说明

MCP GitLab服务器

模型上下文协议（MCP）服务器，提供全面的GitLab API集成。此服务器使LLM能够与GitLab存储库交互，管理合并请求、问题并执行各种Git操作。

特性

核心功能

🔐 身份验证和用户 -获取当前用户信息并查找用户配置文件
🔍 项目管理 -列出、搜索并获取有关GitLab项目的详细信息
📝 问题 -列出、阅读、搜索和评论问题
🔀 合并请求 -列出、读取、更新、批准和合并MR
📁 存储库文件 -浏览、读取和提交对文件的更改
🌳 分支和标签 -列出并管理分支和标签
🔧 CI/CD管道 -查看管道状态、作业和工件
💬 讨论 -阅读并解决合并请求讨论
🎯 智能运营 -批处理操作、人工智能摘要和智能差异

高级功能

批量操作 -使用回滚支持原子地执行多个GitLab操作
AI优化摘要 -生成MR、问题和管道的简明摘要
智能差异 -通过可配置的上下文和大小限制获得结构化差异
安全预览 -提交前预览文件更改
交叉引用支持 -批处理模式下先前操作的参考结果

安装

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

# Run directly without installation
uvx mcp-gitlab

来源

# Clone the repository
git clone https://github.com/Vijay-Duke/mcp-gitlab.git
cd mcp-gitlab

# Install dependencies and run with uv
uv sync
uv run mcp-gitlab

# Or install in development mode with test dependencies
uv sync --all-extras
uv run pytest  # to run tests

配置

环境变量

设置以下身份验证令牌之一：

# Private token (recommended for personal use)
export GITLAB_PRIVATE_TOKEN="your-private-token"

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

# GitLab URL (optional, defaults to https://gitlab.com)
export GITLAB_URL="https://gitlab.example.com"

获取GitLab代币

转到您的GitLab配置文件设置
导航到“访问令牌”
创建具有以下作用域的新令牌：
- api -API完全访问
- read_repository -读取存储库内容
- write_repository -编写存储库内容（用于提交）

用法

使用克劳德桌面

添加到您的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运行

运行MCP GitLab服务器的最简单方法是使用 uvx:

# Set your GitLab token
export GITLAB_PRIVATE_TOKEN="your-token-here"

# Run the server directly with uvx
uvx mcp-gitlab

独立使用

# If running from source (after uv sync)
uv run mcp-gitlab

# Or run the Python module directly
uv run python -m mcp_gitlab

可用工具

身份验证和用户信息

`gitlab_get_current_user`

获取当前经过身份验证的用户的个人资料信息。

{}

返回全面的信息，包括：

基本信息：ID、用户名、姓名、电子邮件
个人资料详细信息：简历、组织、职位
帐户状态：状态、创建日期、管理员状态
权限：can_create_group、can_create_project
安全性：双因素启用，外部状态

`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`

总结用户最近对问题、MR和提交的贡献。

{
  "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`

获取MR，其中用户被指定为具有待处理操作的审阅者。

{
  "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
用户问题和MR: 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
网络钩子: 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

例子

自动检测并列出问题

# First get current project from git repo
project = await session.call_tool("gitlab_get_current_project")

# Then list open issues
issues = await session.call_tool("gitlab_list_issues", {
    "state": "opened"
})

使用批处理操作创建修复

# Atomically: get issue → create branch → commit fix → create MR
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}}"
            }
        }
    ]
})

发展

快速开始

# Install development dependencies
make install-dev

# Run all checks locally
make ci-local

# Format code
make format

# Run tests with coverage
make test-cov

CI/CD管道

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

CI管道：每次推送和公关都会运行
- Linting（Ruff、Black、isort、MyPy）
- 测试（带覆盖率的pytest）
- 安全扫描（Bandit、安全、pip审计）
- 多版本Python测试（3.10、3.11、3.12）
代码质量:
- SonarCloud分析
- CodeQL安全分析
- 复杂性度量（氡、氙）
释放管道：版本标签上的自动发布
- PyPI包发布
- Docker镜像构建和发布
- GitHub发布创建

运行测试

# Run all tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=mcp_gitlab

# Run specific test file
uv run pytest tests/test_gitlab_client.py -v

代码的风格

该项目使用：

黑色用于代码格式化
isort用于导入排序
8号棉绒片
mypy用于类型检查

# Format code
black src/ tests/
isort src/ tests/

# Run linters
flake8 src/ tests/
mypy src/

故障排除

身份验证问题

确保您的令牌具有所需的作用域(api, read_repository, write_repository)
检查令牌到期日期
如果使用自托管实例，请验证GitLab URL

速率限制

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

大量响应

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

贡献

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

许可证

此项目根据Apache许可证2.0获得许可-请参阅许可证文件以获取详细信息。

致谢

建立在模型上下文协议
用途 python gitlab 用于GitLab API交互
受更好的LLM GitLab集成需求的启发

使用说明

MCP GitLab服务器

特性

核心功能

高级功能

安装

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

来源

配置

环境变量

获取GitLab代币

用法

使用克劳德桌面

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

使用uv（如果您已经克隆了存储库）：

用uvx运行

独立使用

可用工具

身份验证和用户信息

gitlab_get_current_user

gitlab_get_user

项目管理

gitlab_list_projects

gitlab_get_project

gitlab_get_current_project

问题

gitlab_list_issues

gitlab_get_issue

gitlab_add_issue_comment

合并请求

gitlab_list_merge_requests

gitlab_get_merge_request

gitlab_update_merge_request

gitlab_merge_merge_request

gitlab_approve_merge_request

存储库操作

gitlab_get_file_content

gitlab_create_commit

gitlab_compare_refs