Skip to main content
Glama
shou-nian

GitLab MCP Server

by shou-nian
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

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

Related MCP server: gitlab-mcp-server

安装

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

更多信息：

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • GitLab + Jira MCP Server

    ashabbir
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables read-only access to GitLab and Jira data through MCP, allowing users to list projects, merge requests, issues, and search Jira tickets via natural language queries. Provides safe, structured access to project management data without write permissions.
    6 npm
    MIT

  • gitlab-mcp-server

    elisjetmax
    A
    license
    Not graded
    quality
    D
    maintenance
    A read-only MCP server for self-hosted GitLab, enabling listing projects, inspecting branches and commits, browsing file trees, and reading file contents.
    10 npm
    ISC

  • GitLab MCP Server

    LoindP
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables interaction with GitLab via the GitLab REST API v4, providing tools for managing projects, merge requests, issues, pipelines, and more through MCP.
    10 npm
    ISC