GitLab MCP服务器（horodchukanton） - MCP Server 功能介绍与安装配置

Name: GitLab MCP服务器
Author: horodchukanton

使用说明

此项目已存档

考虑使用官方 glab mcp 相反

{
  "mcpServers": {
    "glab": {
      "type": "stdio",
      "command": "glab",
      "args": ["mcp", "serve"]
    }
  }
}

GitLab MCP服务器

A. 生产就绪 GitLab的模型上下文协议（MCP）服务器，与IntelliJ IDEA中的GitHub Copilot集成。从git远程自动检测您的GitLab项目，通过智能轮询监控管道和作业状态，并提供可靠的带有重试逻辑的API集成。

状态: ✅ 完全验证 （35次测试，100%通过率）

快速开始

1.安装依赖项

# Runtime dependencies
pip install -r requirements.txt

# Development/test dependencies (optional)
pip install -r requirements-dev.txt

2.配置环境

# Copy the example configuration
cp .env.example .env

# Edit .env with your GitLab credentials
# GITLAB_URL=https://your-gitlab-instance.com
# GITLAB_TOKEN=glpat-xxx

如何获取GitLab代币：

GitLab设置→ 个人访问令牌
创建具有作用域的令牌： api, read_api, read_repository
将令牌值复制到 .env

3.启动服务器

# Using the startup script
./run.sh

# Or directly
python -m src.server

预期产量：

2026-02-10 13:15:30,123 - src.server - INFO - Initializing GitLab MCP server for https://...
2026-02-10 13:15:30,456 - src.server - INFO - GitLab authentication successful
2026-02-10 13:15:30,789 - src.server - INFO - Tools registered successfully
2026-02-10 13:15:30,900 - src.server - INFO - GitLab MCP server started, listening on stdio

4.在IntelliJ IDEA中配置

安装GitHub Copilot插件（如果尚未安装）
设置→ 工具→ GitHub Copilot→ MCP服务器
添加MCP服务器：
- 类型: stdio
- 命令: python -m src.server
- 环境：指向您的 .env 文件

特性

✅ 自动项目检测

无需指定项目路径
从git远程源自动检测
适用于SSH和HTTPS URL
支持嵌套的GitLab组

✅ 管道状态监测

实时管道状态
所有作业详细信息和状态
自动分支和提交检测
人类可读的格式化输出

✅ 智能轮询的作业状态

每2秒轮询一次作业完成情况
可配置超时（默认30秒）
返回中间状态
轮询响应中包含的元数据

✅ 可靠的API集成

3次指数回退重试（1秒、5秒、9秒）
优雅地处理瞬态网络故障
会话级项目ID缓存
清除调试错误消息

✅ 自托管GitLab支持

适用于任何自托管的GitLab实例
不依赖gitlab.com
API完全兼容

可用工具

`check_pipeline_status`

获取当前项目和分支的管道状态

Input:  working_directory (string)
        Optional: branch (string), commit (string)
Output: Pipeline status report with all jobs

它的作用：

自动检测：项目、分支、从git仓库提交
返回：管道ID、状态、具有单个状态的作业
格式：人类可读的文本报告
包括：时间、网址、舞台信息

例子：

# In Copilot context:
# "Check the pipeline status for this project"
# → Copilot calls: check_pipeline_status("/path/to/repo")

`check_job_status`

使用自动轮询检查特定作业状态

Input:  working_directory (string)
        job_name (string) OR job_id (integer)
Output: Job status report with polling metadata

它的作用：

自动检测：来自当前分支/提交的项目、管道
搜索：按作业名称或数字作业ID
投票：每2秒一次，直到完成（最多30秒）
返回：作业状态、计时、日志URL、轮询元数据
元数据： is_polling, polling_timeout, polling_duration_seconds

例子：

# In Copilot context:
# "Check the status of the 'test' job"
# → Copilot calls: check_job_status("/path/to/repo", job_name="test")

项目结构

gitlab-mcp/
├── src/
│   ├── __init__.py
│   ├── server.py              # MCP server entry point
│   ├── mcp_tools.py           # Tool definitions & logic
│   ├── gitlab_client.py       # GitLab API wrapper (retry logic, caching)
│   └── git_utils.py           # Git utilities (URL parsing, branch detection)
│
├── tests/                      # Comprehensive test suite
│   ├── test_gitlab_client.py  # 9 tests for API client
│   ├── test_git_utils.py      # 11 tests for git utilities
│   ├── test_mcp_tools.py      # 10 tests for tool logic
│   ├── test_server.py         # 5 tests for server initialization
│   └── conftest.py            # Pytest configuration
│
├── requirements.txt            # Runtime dependencies
├── requirements-dev.txt        # Test dependencies
├── .env.example               # Configuration template
├── pytest.ini                 # Pytest settings
├── run.sh                     # Startup script
└── README.md                  # This file

运行测试

快速试运行

# Run all tests
python -m pytest tests/ -v

# Quick summary
python -m pytest tests/ -q

测试覆盖率

总测试：35（100%通过率✅)
测试模块：所有4个核心模块
- gitlab_client.py：9个测试（API客户端、重试逻辑、缓存）
- git_utils.py：11个测试（URL解析、验证）
- mcp_tools.py：10个测试（轮询、格式化、逻辑）
- server.py：5个测试（初始化、配置）

运行特定测试

# Test GitLab client
python -m pytest tests/test_gitlab_client.py -v

# Test git utilities
python -m pytest tests/test_git_utils.py -v

# Test MCP tools
python -m pytest tests/test_mcp_tools.py -v

# Test server
python -m pytest tests/test_server.py -v

# Run with coverage
python -m pytest tests/ --cov=src --cov-report=html

配置

环境变量

创建 .env 文件包含：

# Required
GITLAB_URL=https://your-gitlab-instance.com
GITLAB_TOKEN=glpat-your-token-here

# Optional
DEBUG=false  # Set to 'true' for verbose logging

重试逻辑配置

客户端自动重试失败的API调用：

总尝试次数：3（初始+2次重试）
回退延迟：1秒、5秒、9秒
适用于：所有GitLab API调用

作业轮询配置

通过代码配置轮询行为：

# Default settings
_poll_job_status(client, project, job_name, job_id,
                timeout_seconds=30,    # Max wait time
                poll_interval=2.0)      # Check every 2 seconds

建筑

┌─────────────────────────────────────────────┐
│  IntelliJ IDEA + GitHub Copilot Plugin      │
│  (IDE Client)                               │
└──────────────────┬──────────────────────────┘
                   │ (stdio transport)
                   │ (MCP Protocol)
                   │
┌──────────────────▼──────────────────────────┐
│  FastMCP Server (Python)                    │
│  ┌────────────────────────────────────────┐ │
│  │ MCP Tools                              │ │
│  │ • check_pipeline_status                │ │
│  │ • check_job_status (with polling)      │ │
│  └────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────┐ │
│  │ GitLab Client                          │ │
│  │ • Session-based caching                │ │
│  │ • Retry logic (1s, 5s, 9s backoff)     │ │
│  │ • Pipeline/job/MR queries              │ │
│  └────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────┐ │
│  │ Git Utilities                          │ │
│  │ • SSH/HTTPS URL parsing                │ │
│  │ • Branch/commit detection              │ │
│  │ • Repository validation                │ │
│  └────────────────────────────────────────┘ │
└──────────────────┬──────────────────────────┘
                   │ (HTTP REST API)
                   │
┌──────────────────▼──────────────────────────┐
│  Self-Hosted GitLab Instance                │
│  (or gitlab.com)                            │
└─────────────────────────────────────────────┘

故障排除

配置问题

“未设置GITLAB_URL环境变量”

验证 .env 文件存在： ls -la .env
检查 .env 具有GITLAB_URL： grep GITLAB_URL .env
确保 .env 运行服务器时位于工作目录中

“未设置GITLAB_TOKEN环境变量”

添加 GITLAB_TOKEN 到 .env
令牌格式： glpat-xxx （GitLab个人访问令牌）
验证令牌的作用域是否正确： api, read_api, read_repository

“GitLab身份验证成功”，但工具失败

检查GitLab实例是否可访问： curl -H "PRIVATE-TOKEN: $TOKEN" $GITLAB_URL/api/v4/user
验证令牌的作用域是否正确
检查GitLab实例的防火墙/网络访问权限

Git问题

“不是git存储库”

确保你在git仓库中： git remote -v
支持的远程格式：
- git@gitlab.host:group/project.git
- https://gitlab.host/group/project.git
- https://gitlab.host/group/project （不含.git）
- http://gitlab.host/group/project （HTTP，不是HTTPS）

“无法解析git远程URL”

检查git远程格式： git remote -v
SSH和HTTPS都必须采用标准的GitLab格式
支持嵌套组： company/team/project

管道/作业问题

“未找到分支的管道”

验证分支是否已被推送： git push
检查GitLab中是否配置了管道触发器
尝试使用显式提交SHA： check_pipeline_status(dir, commit="abc123")

“未找到作业：测试”

验证作业名称是否完全匹配（区分大小写）
检查管道是否有作业（可能为空）
列出作业： check_pipeline_status(dir) 查看所有工作

作业轮询超时（30秒）

作业未在2分钟窗口内开始
可以重新运行工具以检查当前状态
即使在超时后，工具也会返回上次已知的状态

调试模式

启用详细日志记录：

# In .env
DEBUG=true

# Or as environment variable
DEBUG=true python -m src.server

在工具调用期间检查日志以获取详细的错误消息。

验证与测试

测试结果

============================= 35 passed in 12.73s ===============================
✅ test_git_utils.py         (11 tests)
✅ test_gitlab_client.py      (9 tests)
✅ test_mcp_tools.py         (10 tests)
✅ test_server.py             (5 tests)

测试内容

✅ 带有模拟响应的GitLab API客户端
✅ 重试逻辑和指数回退
✅ 项目ID缓存机制
✅ Git URL解析（SSH、HTTPS、嵌套组）
✅ 作业轮询超时
✅ 响应格式
✅ 服务器初始化和配置
✅ 错误处理和验证

没有真实GitLab实例的测试

所有测试都使用模拟的GitLab API（不需要真正的API调用）：

python -m pytest tests/ -v

演出

典型响应时间

第一个API调用：1-3秒（取决于网络）
后续通话：<500ms（缓存的项目ID）
作业轮询：2秒间隔
总测试套件：约13秒

缓存策略

项目编号：按服务器会话缓存
重置：服务器重新启动会清除缓存
利益：减少对重复操作的API调用

实现细节

重试逻辑

Attempt 1: Immediate call
  ↓ (fails)
Wait 1 second
Attempt 2: Retry
  ↓ (fails)
Wait 5 seconds
Attempt 3: Final retry
  ↓ (fails)
Raise GitLabClientError

URL解析示例

SSH:   git@gitlab.com:group/project.git          → group/project
HTTPS: https://gitlab.com/group/project.git      → group/project
HTTPS: https://gitlab.com/group/project          → group/project
SSH:   git@host:company/team/subteam/project.git → company/team/subteam/project

作业轮询行为

Initial check: Get job status immediately
  ↓
If terminal state (success/failed/canceled/skipped): Return
  ↓
If not started: Polling loop
  ├─ Check every 2 seconds
  ├─ Max 30 seconds total
  └─ Return with polling_timeout flag if timeout occurs

支持的Git存储库

✅ 自托管GitLab实例 （任何版本） ✅ gitlab.com （公共GitLab） ✅ 嵌套组 （公司/团队/项目/…） ✅ SSH和HTTPS远程

❌ 不支持：GitHub、Bitbucket等。（仅限GitLab）

下一步做什么

1.本地测试

# Test git utilities
python -c "
from src.git_utils import get_project_path_from_working_dir
print(get_project_path_from_working_dir('.'))
"

2.测试GitLab连接

python -c "
import os
from dotenv import load_dotenv
from src.gitlab_client import GitLabClient
load_dotenv()
client = GitLabClient(os.getenv('GITLAB_URL'), os.getenv('GITLAB_TOKEN'))
client.gl.auth()
print('✓ GitLab auth successful')
"

3.启动服务器

./run.sh
# Then configure in IntelliJ IDEA GitHub Copilot plugin

4.与Copilot配合使用

在IntelliJ IDEA with Copilot中：

“检查管道状态”
“测试作业的状态如何？”
“显示最新的管道”

贡献

要添加测试或功能，请执行以下操作：

在中创建测试文件 tests/ 目录
对GitLab API使用mocking： patch('src.gitlab_client.gitlab.Gitlab')
运行测试： python -m pytest tests/ -v
在提交之前，确保所有测试都通过

依赖项

运行时

fastmcp>=2.14.0 -模型上下文协议服务器
python-gitlab>=4.0.0 -GitLab API客户端
python-dotenv>=1.0.0 -环境变量加载
GitPython>=3.1.0 -Git操作

开发/测试

pytest>=8.0.0 -测试框架
requests-mock>=1.11.0 -HTTP模拟（可选）

实施状态

功能	状态	测试
管道状态监测	✅ 完成	4
作业状态查找	✅ 完成	5
作业轮询	✅ 完成	4
Git URL解析	✅ 完成	8
重试逻辑	✅ 完成	1
错误处理	✅ 完成	3
服务器初始化	✅ 完成	5
配置验证	✅ 完成	5

支持

对于问题或疑问：

启用调试日志：设置 DEBUG=true 在 .env
检查日志：在工具调用期间查看服务器输出
验证设置：按照上面的故障排除部分进行操作
审查测试：检查 tests/ 使用示例
检查git遥控器: git remote -v 必须是有效的GitLab URL

许可证

[在此处添加您的许可证]

最后验证2026年2月10日
测试套件：35/35传球✅
状态：生产就绪🚀

使用说明

此项目已存档

GitLab MCP服务器

快速开始

1.安装依赖项

2.配置环境

3.启动服务器

4.在IntelliJ IDEA中配置

特性

✅ 自动项目检测

✅ 管道状态监测

✅ 智能轮询的作业状态

✅ 可靠的API集成

✅ 自托管GitLab支持

可用工具

check_pipeline_status

check_job_status

项目结构

运行测试

快速试运行

测试覆盖率

运行特定测试

配置

环境变量

重试逻辑配置

作业轮询配置

建筑

故障排除

配置问题

Git问题

管道/作业问题

调试模式

验证与测试

测试结果

测试内容

没有真实GitLab实例的测试

演出

典型响应时间

缓存策略

实现细节

重试逻辑

URL解析示例

作业轮询行为

支持的Git存储库

下一步做什么

1.本地测试

2.测试GitLab连接

3.启动服务器

4.与Copilot配合使用

贡献

依赖项

运行时

开发/测试

实施状态

支持

许可证

相关 MCP

GitLab集成服务器

CERN GitLab MCP服务器

GitLab代码审查工具

代码审查工具

GitLab API集成服务器

GitLab MCP连接器

`check_pipeline_status`

`check_job_status`