mcp-gitlab-server

mcp-gitlab-server

⚠️ 开发阶段提示
此项目目前处于开发阶段。功能和 API 可能会在不另行通知的情况下变更。在生产环境中使用时请谨慎。

基于 python-gitlab 的 GitLab MCP 服务。

安装

使用个人访问令牌（最常见）

{
  "mcpServers": {
    "GitLab": {
      "command": "uvx",
      "args": [
        "gitlab-mcp-server"
      ],
      "env": {
        "GITLAB_TOKEN": "<your GitLab personal access token>",
        "GITLAB_URL": "https://gitlab.com"
      }
    }
  }
}

使用 OAuth2 令牌

{
  "mcpServers": {
    "GitLab": {
      "command": "uvx",
      "args": [
        "gitlab-mcp-server"
      ],
      "env": {
        "GITLAB_OAUTH_TOKEN": "<your GitLab OAuth2 token>",
        "GITLAB_URL": "https://gitlab.com"
      }
    }
  }
}

对于自托管的 GitLab 实例，请将 GITLAB_URL 设置为你的 GitLab 实例 URL（例如，https://gitlab.example.com）。如果未设置，默认值为 https://gitlab.com。

身份验证

此 MCP 服务支持两种身份验证方式：

方式 1：个人访问令牌（推荐大多数用户使用）

1. 创建 GitLab 个人访问令牌：

   • 前往 GitLab → 用户设置 → 访问令牌
   • 创建一个具有 read_api 范围的令牌（最低要求）

2. 将 GITLAB_TOKEN 环境变量设置为你的令牌值

方式 2：OAuth2 令牌（适用于 OAuth2 应用）

1. 如果你通过 GitLab OAuth2 应用流程获得了 OAuth2 令牌
2. 将 GITLAB_OAUTH_TOKEN 环境变量设置为你的 OAuth2 令牌值

创建 OAuth2 应用：

1. 前往 GitLab → 用户设置 → 应用程序
2. 创建一个具有适当范围的新应用程序（最低要求为 read_api）
3. 使用 OAuth2 流程获取访问令牌
4. 将该令牌用作 GITLAB_OAUTH_TOKEN

环境变量

• GITLAB_TOKEN - 你的 GitLab 个人访问令牌（使用个人令牌身份验证时）
• GITLAB_OAUTH_TOKEN - 你的 GitLab OAuth2 令牌（使用 OAuth2 身份验证时）
• GITLAB_URL - GitLab 实例 URL（默认为 https://gitlab.com）

注意： 服务会先检查 GITLAB_OAUTH_TOKEN；如果未找到，则使用 GITLAB_TOKEN。只需设置其中一个即可。

工具

仓库与项目管理

• list_projects - 列出经过身份验证的用户可访问的 GitLab 项目（支持按所属项目或已加星标项目筛选，并支持分页）
• list_groups - 列出经过身份验证的用户可访问的 GitLab 群组
• list_group_projects - 列出指定 GitLab 群组中的所有项目
• get_user_info - 获取经过身份验证的用户信息
• search_repositories - 按名称、描述或关键词搜索 GitLab 仓库
• get_repository_details - 获取指定仓库的详细信息

代码访问

• read_repository_code - 通过筛选选项读取仓库的完整代码结构和内容
• read_repository_file - 读取仓库中特定文件的内容

合并请求分析

• list_merge_requests - 列出仓库的合并请求，支持按状态筛选、排序和分页
• get_merge_request_analytics - 计算全面的合并请求生命周期统计数据，包括从创建到合并的平均耗时

仓库代码读取功能

此 MCP 服务提供强大的代码读取功能：

read_repository_code

通过高级筛选功能读取整个仓库的结构和文件内容：

• 选择性读取：使用 glob 模式包含或排除文件（例如，*.py,*.js，或排除 *.log,node_modules/*）
• 大小限制：控制要读取的最大文件数和文件大小限制，避免响应过大
• 分支/标签支持：从任意分支、标签或提交 SHA 读取
• 目录筛选：专注于仓库中的特定目录
• 智能筛选：自动排除常见的构建产物、日志和二进制文件

使用示例：

• 仅读取 Python 文件：include_patterns: "*.py"
• 排除测试文件：exclude_patterns: "*test*,*spec*"
• 读取指定目录：path: "src/"
• 使用其他分支：ref: "develop"

read_repository_file

读取仓库中的单个文件：

• 单文件访问：快速获取特定文件的内容
• 包含元数据：文件大小、编码、最后一次提交信息
• 二进制文件检测：安全处理二进制文件
• 灵活引用：支持分支、标签或提交 SHA

限制与安全性：

• 默认：最多 50 个文件，每个文件 100KB
• 可配置限制以避免超时
• 自动检测二进制文件
• 妥善处理大型仓库中的错误

合并请求分析功能

MCP 服务提供全面的合并请求分析功能：

list_merge_requests

使用高级筛选和排序功能列出合并请求：

• 状态筛选：按状态筛选（opened、closed、merged、all）
• 灵活排序：按创建日期、更新日期或标题排序
• 丰富的元数据：包含作者、指派人员、审阅者、标签和投票信息
• 支持分页：控制返回结果的数量

get_merge_request_analytics

计算详细的合并请求生命周期统计数据：

• 生命周期分析：从创建到合并的平均、中位、最短和最长耗时
• 统计分布：第 25、75 和 90 百分位分析
• 时间范围控制：分析过去 N 天的 MR（默认：90 天）
• 详细分类：包含各个 MR 的详细信息及精确的生命周期计算
• 多种时间单位：结果同时以小时和天为单位提供

可回答的问题示例：

• “acapulco 仓库中 MR 的平均生命周期是多少？”
• “合并请求通常需要多长时间才能合并？”
• “合并请求的生命周期分布情况如何？”
• “哪些合并请求花费了最长时间才合并？”

分析输出：

• 平均、中位、最短、最长合并耗时
• 百分位分析（第 25、75、90 百分位）
• 带有各自生命周期的示例合并请求
• 可供进一步分析的完整数据集

开发

# Clone the repository
git clone <repo-url>
cd gitlab-mcp-server

# Install dependencies
uv sync

# Run in development mode
uv run python -m mcp_gitlab_server

测试配置

出于开发和测试目的，你可以使用本地 wheel 文件进行安装：

用于测试的 MCP 配置：

{
  "mcpServers": {
    "GitLab": {
      "command": "uvx",
      "args": [
        "--from", "/path/to/your/gitlab-mcp-server/dist/mcp_gitlab_server-0.1.0-py3-none-any.whl",
        "gitlab-mcp-server"
      ],
      "env": {
        "GITLAB_TOKEN": "your-gitlab-token-here",
        "GITLAB_URL": "https://gitlab.com"
      }
    }
  }
}

构建和测试步骤：

# Build the wheel file
uv build

# Test with MCP client (like Claude Desktop)
# Update your MCP configuration with the local wheel path
# The wheel file will be in ./dist/ directory

# For quick testing, verify the server starts:
uv run python -m mcp_gitlab_server