GitLab MCP Server

一个基于官方 MCP Python SDK 的只读 GitLab MCP Server。它通过 stdio 向 Codex 等 MCP Client 暴露结构化 Tool，并由独立的异步 Client 调用 GitLab REST API v4。

当前版本只提供以下能力：

• gitlab_get_project：获取项目信息
• gitlab_get_file：读取仓库文件和元数据
• gitlab_list_files：列出仓库目录内容
• gitlab_get_merge_request：获取 Merge Request 信息

项目不会创建、修改或删除任何 GitLab 数据。

环境要求

• Python 3.11 或更高版本
• uv
• 可访问目标 GitLab 实例的网络
• 建议使用仅含 read_api 权限的 GitLab Access Token

安装

git clone <repository-url>
cd gitlab-mcp-server
uv sync

uv sync 会严格按照 uv.lock 创建或更新项目虚拟环境。项目不使用 pip、Poetry 或 Pipenv。

配置

复制示例配置并填写 GitLab 信息：

cp .env.example .env

Windows PowerShell：

Copy-Item .env.example .env

环境变量说明：

变量	必填	默认值	说明
GITLAB_URL	是	无	GitLab 实例根地址，例如 https://gitlab.example.com
GITLAB_TOKEN	是	无	GitLab Access Token；日志不会输出该值
GITLAB_TIMEOUT	否	30	GitLab HTTP 请求超时秒数，必须大于 0
LOG_LEVEL	否	INFO	Python 日志级别

环境变量优先于 .env。不要把 .env 提交到版本库。

启动

uv run gitlab-mcp

Server 使用 stdio 传输；直接启动后等待 MCP Client 消息属于正常行为。日志写入 stderr，不会污染 MCP 协议的 stdout。

Server 支持优雅退出。MCP Client 关闭 stdin、发送 SIGINT（如 Ctrl+C）或发送 SIGTERM 时，Server 会停止接收请求、取消仍在执行的任务，并在进程退出前关闭 GitLab HTTP 连接池。正常退出过程及结果只记录到 stderr，不会输出 Python traceback。

也可以使用仓库根兼容入口：

uv run python main.py

Codex / MCP Client 配置

在 Codex 的 config.toml 中添加：

[mcp_servers.gitlab]
command = "uv"
args = ["run", "--directory", "D:/path/to/gitlab-mcp-server", "gitlab-mcp"]

[mcp_servers.gitlab.env]
GITLAB_URL = "https://gitlab.example.com"
GITLAB_TOKEN = "your-read-only-token"
GITLAB_TIMEOUT = "30"

通用 JSON MCP 配置示例：

{
  "mcpServers": {
    "gitlab": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/gitlab-mcp-server",
        "gitlab-mcp"
      ],
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "your-read-only-token"
      }
    }
  }
}

重启 MCP Client 后，应能发现四个以 gitlab_ 开头的 Tool。

调用示例

参数中的 project_id 支持 GitLab 数值项目 ID，也支持 namespace/project 路径。

获取项目：

{
  "name": "gitlab_get_project",
  "arguments": {"project_id": "group/demo"}
}

读取文件：

{
  "name": "gitlab_get_file",
  "arguments": {
    "project_id": "group/demo",
    "file_path": "src/app.py",
    "ref": "main"
  }
}

GitLab Files API 的 content 字段通常为 base64。Server 会保留 GitLab 原始 encoding 和 content，由调用方按需解码。

列出目录：

{
  "name": "gitlab_list_files",
  "arguments": {
    "project_id": 42,
    "path": "src",
    "ref": "main",
    "recursive": false
  }
}

获取 Merge Request：

{
  "name": "gitlab_get_merge_request",
  "arguments": {
    "project_id": 42,
    "merge_request_iid": 7
  }
}

成功响应统一为 {"success": true, "data": ...}，参数错误或 GitLab API 错误统一为 {"success": false, "error": ...}。

开发与测试

测试全部使用 AsyncMock 或 httpx.MockTransport，不会访问真实 GitLab：

uv run pytest -q
uv run ruff check src tests main.py
uv run ruff format --check src tests main.py

更多信息：

• 架构设计
• Tool 说明
• GitLab API 映射