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

Name: GitLab MCP API服务器
Author: 13shivam

使用说明

EGMA：增强型GitLab MCP API服务器

一个用于GitLab集成的模型上下文协议（MCP）服务器，使用官方工具构建 Python-gitlab SDK通过143+种专业工具，为AI助手提供智能的GitLab访问权限。

✨ 主要特点

🔧 143+ 工具 - 项目、问题、合并请求（MRs）、流水线、搜索、仓库操作
🧠 智能上下文 - URL推断，实体识别，对话连贯性
🛡️ 安全 - 默认只读，可配置访问控制
⚡ 优化了 - 缓存、速率限制、智能过滤
🔌 兼容 - 与Claude Desktop、Amazon Q、Cursor及其他MCP客户端兼容

🛠 工具分类

类别	工具	描述
项目	24+	智能搜索，活动评分，上下文推断
问题	19+	智能过滤，上下文搜索，URL推断
合并请求	20+	分析、评审助手、冲突检测
管道	19+	健康监测、故障排查、性能分析
搜索	15+	全局搜索、代码搜索、相关性评分
仓库（或存储库）	16+	分支分析，提交洞察，文件操作
将军；总司令	6+	具备处理能力的核心GitLab操作

🏗 建筑

高层视图/概览

GitLab MCP 服务器遵循清晰的架构模式，实现了职责分明的分离：

AI助手用户 通过MCP客户端（Claude Desktop、Amazon Q）进行交互
FastMCP 服务器 处理MCP协议通信
DI 容器 管理依赖关系和服务提供
工具注册表 提供143+种专业的GitLab工具
智能层 支持上下文提取和URL推断
处理流水线 处理内容预处理
缓存层 优化API响应性能

分层视图

该系统被组织成不同的层级：

客户端层 - MCP 客户端（如 Claude Desktop、Amazon Q 等）
入口层（或接入层） - FastMCP服务器，寿命管理器，信号处理器
核心层 - 依赖注入容器（DI Container）、设置（Settings）、缓存管理器（Cache Manager）、速率限制器（Rate Limiter）
服务层 - GitLab 客户端、工具注册表、内容管道
智能层 - 上下文提取器，URL 推断器，实体匹配器
工具层 - 项目、问题、合并请求（Merge Request）、流水线工具
领域层 - 内容上下文，GitLab 模型，错误处理程序
外层 - GitLab API v4

请求流程

交互序列显示：

初始化 - 容器设置、工具注册、验证
请求处理 - 实体提取、内容处理、速率限制
工具执行 根据上面的信息，执行如下指令：你是个专业的翻译，负责把英语内容翻译成中文内容，请帮我翻译一下原文内容
错误处理 - 重试逻辑，错误分类，优雅降级
健康监测 - 连接测试，指标收集

📦 快速入门

先决条件

Docker
亚马逊Q或Claude聊天工具

{
  "mcpServers": {
    "gitlab-mcp-server": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env", "GITLAB_URL=https://personal-gitlab.domain.com",
        "--env", "GITLAB_TOKEN=x0FFF0xCAFEBABE",
        "--env", "MCP_TRANSPORT=stdio",
        "--env", "GITLAB_TIMEOUT=30",
        "--env", "GITLAB_SSL_VERIFY=false",
        "--env", "READ_ONLY_MODE=true",
        "--env", "CACHE_TTL=300",
        "--env", "RATE_LIMIT_REQUESTS=100",
        "--env", "RATE_LIMIT_WINDOW=60",
        "--env", "LOG_LEVEL=INFO",
        "s13dc/gitlab-mcp-server:latest"
      ]
    }
  }
}

高级用户的前提条件

Python 3.10及以上版本
带有（权限）的GitLab个人访问令牌 read_api 并且 read_repository 范围（或“作用域”）

安装

git clone https://github.com/13shivam/gitlab-mcp-server.git
cd gitlab-mcp-server
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

使用紫外线的替代方案（更快）：

uv venv && source .venv/bin/activate && uv pip install -e .

配置

创建 .env 文件：

cp .env.example .env
# Edit .env and add your configuration

所需的环境变量：

GITLAB_TOKEN=your_personal_access_token
GITLAB_URL=https://gitlab.com  # or your GitLab instance

可选配置：

# Security & Access Control
READ_ONLY_MODE=true              # Blocks write operations (default: true)

# Performance & Caching
CACHE_TTL=300                    # Cache TTL in seconds
RATE_LIMIT_REQUESTS=100          # Requests per window
RATE_LIMIT_WINDOW=60             # Window in seconds

# Environment Profile
ENVIRONMENT=development          # development, production, testing

# Logging
LOG_LEVEL=INFO                   # DEBUG, INFO, WARNING, ERROR

🚀 使用方法

启动服务器

source .venv/bin/activate
python -m src.server

MCP 客户端配置

Claude Desktop（桌面版）claude_desktop_config.json):

{
  "mcpServers": {
    "gitlab": {
      "command": "python",
      "args": ["-m", "src.server"],
      "env": {
        "GITLAB_TOKEN": "your_token_here",
        "GITLAB_URL": "https://gitlab.com",
        "MCP_TRANSPORT" : "stdio",
        "GITLAB_TIMEOUT": "30",
        "GITLAB_SSL_VERIFY": "false",
        "READ_ONLY_MODE": "true",
        "CACHE_TTL": "300",
        "RATE_LIMIT_REQUESTS": "100",
        "RATE_LIMIT_WINDOW": "60",
        "LOG_LEVEL": "INFO"
      },
      "cwd": "/path/to/gitlab-mcp-server"
    }
  }
}

Amazon Q 开发者：

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server/.venv/bin/python",
      "args": ["-m", "src.server"],
      "env": {
        "GITLAB_TOKEN": "your_token_here",
        "GITLAB_URL": "https://gitlab.com",
        "MCP_TRANSPORT" : "stdio",
        "GITLAB_TIMEOUT": "30",
        "GITLAB_SSL_VERIFY": "false",
        "READ_ONLY_MODE": "true",
        "CACHE_TTL": "300",
        "RATE_LIMIT_REQUESTS": "100",
        "RATE_LIMIT_WINDOW": "60",
        "LOG_LEVEL": "INFO"
      },
      "cwd": "/path/to/gitlab-mcp-server"
    }
  }
}

🧠 智能功能

情境感知

**URL 推断（或 URL 推导）**自动从GitLab URL中提取项目ID、问题编号和合并请求（MR）引用
实体识别从对话中解析项目路径、用户提及和提交哈希（SHA）
上下文连贯性记住多个工具调用之间的项目上下文
智能参数填充从对话历史中自动补全缺失的参数

自然语言理解

User: "Show me failing tests in the login MR for the auth project"
System: 
- Extracts: project="auth", MR topic="login", focus="failing tests"
- Suggests: gitlab_get_mr_with_analysis + gitlab_troubleshoot_failed_pipeline
- Auto-fills: project context, searches for login-related MRs

智能分析

相关性评分根据用户查询的相关性对搜索结果进行排序
健康监测主动洞察管道健康状况和项目状态
趋势分析识别CI/CD性能、问题解决等方面的模式。
建议基于数据分析的可行建议

🔧 开发

开发环境设置

带有紫外线功能（推荐）：

# Install UV: https://github.com/astral-sh/uv
git clone https://github.com/13shivam/gitlab-mcp-server.git
cd gitlab-mcp-server
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

使用Classic pip：

git clone https://github.com/13shivam/gitlab-mcp-server.git
cd gitlab-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

快速设置：

安装依赖项： pip install -e .
配置 .env 使用您从（某处）获取的GitLab令牌 .env.example
运行服务器： python -m src.server

测试

该项目包括单元测试和集成测试，以实现全面覆盖。

单元测试

# Run all unit tests
pytest tests/tools/ -v

# Run specific tool tests
pytest tests/tools/test_general_tools.py -v
pytest tests/tools/test_project_tools.py -v
pytest tests/tools/test_issue_tools.py -v

# Run with coverage report (requires pytest-cov)
pip install pytest-cov
pytest tests/tools/ --cov=src/tools --cov-report=html

集成测试

该项目包括全面的集成测试：

使用以下命令运行集成测试：

# Run all integration tests
python mcp_integration_tests/test_runner.py

# Run specific category
python mcp_integration_tests/test_runner.py --category projects

# Run with detailed output
python mcp_integration_tests/test_runner.py --verbose

🛡 安全与配置

只读模式

READ_ONLY_MODE=true  # Blocks all write operations (default: true)

环境特定的默认值：

生产永远 true （为安全起见而强制执行）
发展： false （允许写入操作）
测试： true （为安全起见而强制执行）

高级配置

# Tool & Category Filtering (Optional)
# ENABLED_TOOLS=gitlab_get_project,gitlab_list_issues
# ENABLED_CATEGORIES=projects,issues

# Performance & Caching
CACHE_TTL=300                    # Cache TTL in seconds
RATE_LIMIT_REQUESTS=100          # Requests per window
RATE_LIMIT_WINDOW=60             # Window in seconds

# Transport Mode (Optional)
MCP_TRANSPORT=stdio              # stdio (default), sse, streamable-http
MCP_HOST=0.0.0.0                 # Host for HTTP transports
MCP_PORT=8000                    # Port for HTTP transports

# Optional Settings
GITLAB_TIMEOUT=30
GITLAB_SSL_VERIFY=false

🚨 故障排除

身份验证问题

# Test token manually
curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" $GITLAB_URL/api/v4/user

连接问题

验证 GITLAB_URL 是正确的
检查网络连接： ping gitlab.com
确保令牌具有所需的范围： read_api， read_repository
设置 GITLAB_SSL_VERIFY=false 用于自签名证书

服务器健康监控

# Quick health check
python -m src.server --health-check

# Configuration validation
python -m src.server --validate-only

# Or use the MCP tool: gitlab_server_health_complete()

🎯 示例用例

智能问题管理

"Show me critical bugs assigned to me in the auth project"
→ Auto-deduces project, filters by labels and assignee

智能MR评测

"Review this MR: https://gitlab.com/project/repo/-/merge_requests/123"
→ Extracts URL, analyzes MR, provides review checklist

CI/CD 健康监控

"How are our pipelines performing this month?"
→ Analyzes trends, identifies bottlenecks, suggests optimizations

情境感知搜索

"Find recent login issues" (after mentioning a project)
→ Remembers project context, searches with relevant filters

🤝 贡献（或：参与贡献）

为仓库创建分支
创建一个特性分支： git checkout -b feature/amazing-feature
进行更改并添加测试
运行测试套件： python mcp_integration_tests/test_runner.py
提交您的更改： git commit -m 'Add amazing feature'
推送到分支： git push origin feature/amazing-feature
提交一个拉取请求

📄 许可证

麻省理工学院许可证（MIT License）