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

Name: GitLab MCP服务器
Author: nostoslabs

使用说明

GitLab MCP 服务器

一个基于Python的MCP（模型上下文协议）服务器，用于GitLab集成

概述

GitLab MCP Server 是 GitLab 的模型上下文协议（Model Context Protocol）的全面 Python 实现，提供 88种工具 与GitLab的API进行交互。它基于清晰架构原则和FastMCP框架构建，提供了类型安全、经过测试且易于维护的访问GitLab全部功能集的方式。

关键亮点

88 个 GitLab 工具 - 与TypeScript实现完全功能一致
清洁架构 - 四层架构，便于维护和测试
类型安全 - 使用 mypy 严格模式强制执行完整的类型提示
经过充分测试 - 240+个测试，覆盖率72%
已准备好投入生产 - Docker 支持，CI/CD 管道，安全扫描
多种运输方式 - 支持stdio、SSE和可流式HTTP

特点/特性

GitLab 运维（88款工具）

服务器提供了涵盖19个类别的全面GitLab API访问权限：

类别	工具	描述
（内容未提供）	（内容未提供）	（内容未提供）
6	创建、阅读、更新、删除和列出问题	**
9	包括差异（diffs）在内的完整MR（合并请求）生命周期管理	**
5	项目管理与搜索	**
7	CI/CD 管道操作与作业管理	**
4	文件操作和仓库树导航	**
3	创建、删除和列出分支	**
7	维基页面管理及附件管理	**
10	里程碑跟踪和燃尽图	**
3	标签管理与组织	**
2	提交详情和差异	**
2	发布和MR（合并请求）讨论/线程	**
1	用户信息检索	**
1	项目成员管理	**
3	命名空间操作与验证	**
1	团队项目列表	**
2	管道作业控制（播放，取消）	**
2	问题关系追踪	**
0	（计划中 - 请参阅路线图）	**

| 0 | （计划中 - 请参阅路线图） |

架构特性 清洁架构
- 在4个不同层面上实现关注点分离 FastMCP 框架
- 现代以异步优先的MCP（可能指某种通信协议或系统）实现 python-gitlab（可译为“Python GitLab 客户端”或“用于Python的GitLab库”）
官方GitLab Python客户端，用于API访问 Pydantic（注：这是一个专有名词，通常不翻译，直接保留原样，但在中文语境下，有时也会根据上下文进行适当解释或说明，此处直接给出原词）
- 数据验证和设置管理 结构化日志记录
- 使用 structlog 实现生产就绪的日志记录 重试逻辑

- 自动重试，采用指数退避策略（韧性）

安全与质量 只读模式
- 生产环境中的可选安全模式 访问控制
- 项目允许列表/拒绝列表支持 工具过滤
- 基于正则表达式的工具访问控制 类型安全
- 100% 符合 mypy 严格模式 安全扫描
- Bandit 静态分析和 pip-audit（工具） 提交前钩子（Pre-commit Hooks）

- 自动执行代码质量规范

快速入门

先决条件 Python 3.11及以上版本
- 现代类型提示和异步功能所必需 紫外线
- 快速的Python包管理器（推荐） GitLab个人访问令牌

- 配备适当的API范围

# Install uv package manager (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/nostoslabs/gitlab-mcp.git
cd gitlab-mcp

# Install all dependencies
uv sync

# Copy and configure environment variables
cp .env.example .env
# Edit .env and set your GITLAB_PERSONAL_ACCESS_TOKEN

安装

配置 .env 创建一个

# ============================================
# Required Configuration
# ============================================
GITLAB_PERSONAL_ACCESS_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
GITLAB_API_URL=https://gitlab.com  # or your self-hosted GitLab URL

# ============================================
# Optional Configuration
# ============================================

# Project Access Control
GITLAB_PROJECT_ID=123456                      # Default project
GITLAB_ALLOWED_PROJECT_IDS=123456,789012     # Comma-separated list

# Security Features
GITLAB_READ_ONLY_MODE=false                  # Enable read-only mode
GITLAB_DENIED_TOOLS_REGEX=                   # Regex to block tools

# Feature Toggles
USE_GITLAB_WIKI=true                         # Enable wiki tools
USE_MILESTONE=true                           # Enable milestone tools
USE_PIPELINE=true                            # Enable pipeline tools

# Transport Configuration
SSE=false                                    # Server-Sent Events mode
STREAMABLE_HTTP=false                        # Streamable HTTP mode
HOST=127.0.0.1                              # Server host
PORT=8080                                   # Server port

# Network Proxy (optional)
HTTP_PROXY=
HTTPS_PROXY=
NO_PROXY=localhost,127.0.0.1

# Advanced Options
GITLAB_AUTH_COOKIE_PATH=                    # Cookie auth path
GITLAB_COMMIT_FILES_PER_PAGE=20            # Pagination size
LOG_LEVEL=INFO                             # Logging level

使用您的GitLab凭据进行文件操作：

# Run with stdio transport (default)
uv run python -m gitlab_mcp

# Run with Server-Sent Events transport
SSE=true uv run python -m gitlab_mcp

# Run with Streamable HTTP transport
STREAMABLE_HTTP=true HOST=0.0.0.0 PORT=8080 uv run python -m gitlab_mcp

运行服务器

# Run all tests
make test

# Run tests with coverage report
make test-cov

# Run quality checks
make all

测试安装

建筑 GitLab MCP 服务器遵循 清洁架构

┌─────────────────────────────────────────────────────────────┐
│                     Presentation Layer                       │
│  ┌────────────────────────────────────────────────────┐    │
│  │  FastMCP Server (server.py)                        │    │
│  │  • 88 Tool Handlers                                │    │
│  │  • Pydantic Schemas                                │    │
│  │  • Transport: stdio/SSE/HTTP                       │    │
│  └────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                     Application Layer                        │
│  ┌────────────────────────────────────────────────────┐    │
│  │  Use Cases                                          │    │
│  │  • CreateIssue, UpdateMergeRequest, etc.          │    │
│  │  • Business Logic Orchestration                    │    │
│  │  • DTOs (Data Transfer Objects)                   │    │
│  └────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                      Domain Layer                            │
│  ┌────────────────────────────────────────────────────┐    │
│  │  Entities                                           │    │
│  │  • Issue, MergeRequest, Project, Pipeline          │    │
│  │  • Pure business logic (no dependencies)           │    │
│  │  • Value Objects: ProjectId, Pagination            │    │
│  └────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                            ↑
┌─────────────────────────────────────────────────────────────┐
│                    Infrastructure Layer                      │
│  ┌────────────────────────────────────────────────────┐    │
│  │  GitLab API Client (python-gitlab + httpx)         │    │
│  │  • Repository Implementations                       │    │
│  │  • Configuration (Pydantic Settings)               │    │
│  │  • Logging (structlog)                             │    │
│  └────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

具有4个不同层次的原则：

src/gitlab_mcp/
├── domain/                    # Pure business logic (no external deps)
│   ├── entities/             # Issue, MergeRequest, Project, Pipeline
│   └── value_objects/        # ProjectId, Pagination, IssueIid
│
├── application/              # Use cases and orchestration
│   ├── interfaces/          # Repository ports (abstract)
│   ├── dtos/                # Data transfer objects
│   └── use_cases/           # Business logic (CreateIssue, etc.)
│
├── infrastructure/          # External services integration
│   ├── config/             # Pydantic Settings (environment vars)
│   ├── gitlab/             # python-gitlab client & repositories
│   └── logging/            # Structured logging setup
│
├── presentation/           # MCP interface (FastMCP)
│   ├── server.py          # Main FastMCP server setup
│   ├── schemas/           # Pydantic validation schemas
│   └── tools/             # 88 MCP tool handlers (19 categories)
│       ├── issues/
│       ├── merge_requests/
│       ├── projects/
│       ├── pipelines/
│       ├── repository/
│       ├── branches/
│       ├── wikis/
│       ├── milestones/
│       ├── labels/
│       ├── commits/
│       ├── discussions/
│       ├── users/
│       ├── members/
│       ├── namespaces/
│       ├── groups/
│       ├── jobs/
│       ├── issue_links/
│       ├── draft_notes/
│       └── events/
│
├── services/              # Shared services
│   └── gitlab_client_factory.py
│
├── __main__.py           # Entry point
└── server.py             # FastMCP server (main file)

目录结构

发展

# Install development dependencies
uv sync --dev

# Install pre-commit hooks
uv run pre-commit install

# Verify installation
make help

开发环境设置

可用命令

# Code Quality
make format        # Format code with black and ruff
make lint          # Lint code with ruff (must pass with 0 errors)
make type-check    # Type check with mypy (must pass with 0 errors)

# Testing
make test          # Run all tests
make test-cov      # Run tests with coverage report

# Complete Validation
make all           # Run all quality checks (format + lint + type-check + test)

# Cleanup
make clean         # Remove cache and generated files

# Help
make help          # Show all available commands

该项目包含一个全面的Makefile，用于所有开发任务：

质量标准

**所有代码在合并前必须符合这些标准：**Linting（在编程领域，通常指代码检查或代码格式化的过程）
零粗心错误类型检查
零 mypy 错误格式化
黑格式代码测试
所有测试均通过覆盖范围

保持70%以上的总体覆盖率

测试策略 该项目随后进行 测试驱动开发（TDD）

# Unit Tests - Fast, isolated tests
uv run pytest tests/unit/

# Integration Tests - API interaction tests
uv run pytest tests/integration/

# End-to-End Tests - Full workflow tests
uv run pytest tests/e2e/

# Run specific test file
uv run pytest tests/unit/presentation/tools/issues/test_create_issue.py -v

# Run with coverage
uv run pytest --cov=src --cov-report=html --cov-report=term-missing

具有三个测试层：

按层级划分的覆盖目标：
领域层：100%（纯业务逻辑）
应用层：90%+（使用场景）
基础设施层：80%+（外部集成）

表示层：85%+（使用MCP工具）

添加新工具要添加一个新的GitLab工具，请按照以下步骤操作：《实施指南.md》

**：**领域/范围 Issue如有需要，请创建实体（例如。， MergeRequest，
**)**应用程序 CreateIssueUseCase创建包含测试的用例（例如。，
**）**基础设施
实现API调用的存储库方法演示
创建Pydantic模式和MCP工具处理器测试
编写单元测试、集成测试和端到端（e2e）测试文档

更新工具目录和API文档

预提交钩子（Pre-commit Hooks）

该项目使用预提交钩子来确保质量：
去除尾随空格
文件结尾修复器
YAML 验证
大文件检查
黑色格式化
粗略的代码检查（或称为粗略的linting）
Mypy 类型检查

# Run manually
uv run pre-commit run --all-files

Bandit安全扫描

Docker 部署

# Build the Docker image
docker build -t gitlab-mcp .

# Build with specific Python version
docker build --build-arg PYTHON_VERSION=3.12 -t gitlab-mcp:py312 .

构建形象

# Run with environment file
docker run -it --env-file .env gitlab-mcp

# Run with SSE transport
docker run -it --env-file .env -p 8080:8080 -e SSE=true gitlab-mcp

# Run in detached mode
docker run -d --name gitlab-mcp-server --env-file .env gitlab-mcp

使用 Docker 运行

# Start the server
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the server
docker-compose down

# Rebuild and restart
docker-compose up -d --build

Docker Compose

该Docker镜像使用： 多阶段构建
为了达到最小尺寸 Chainguard Python 基础镜像
为了安全起见 健康检查
用于集装箱监控 非root用户

为了安全（计划中）

持续集成/持续交付（CI/CD）

GitHub Actions 工作流

该项目包含5个自动化工作流： CI（企业标识/品牌标识）.github/workflows/ci.yml(
- )
- 代码质量检查（black、ruff、mypy）
- 带有覆盖率的测试执行
- 安全扫描（使用bandit、pip-audit工具）
Codecov 集成 CodeQL.github/workflows/codeql.yml(
- ）
- 安全漏洞扫描
代码质量分析 Docker 发布.github/workflows/docker-publish.yml(
- )
- 自动化Docker镜像构建
推送到容器注册表 发布.github/workflows/release.yml（
- )
- 自动化版本标签生成
发布说明生成 SonarCloud.github/workflows/sonarcloud.yml(
- ）
- 代码质量指标

技术债务追踪

# Run the same checks as CI
make all

# Individual checks
make format
make lint
make type-check
make test-cov

在本地运行持续集成（CI）

文档 docs/ 全面的文档资料可在……中找到

目录： | 文件 | 描述 | |----------|-------------| | ARCHITECTURE.md 翻译为中文是：“架构.md”（其中，“.md”通常表示Markdown文件格式） | 清洁架构原则与分层细节 | | 《实施指南.md》实施工具的分步指南 | 《TESTING_GUIDE.md》翻译为中文是《测试指南.md》 | TDD方法和测试模式 | | QUICK_REFERENCE.md 翻译为中文是：快速参考指南.md | 代码模板和快速代码片段 | | `MISSING_TOOLS_ROADMAP.md` 翻译为中文是：“缺失工具路线图.md”

未来工具实施计划

额外资源TypeScript 参考手册 old/ 原始的TypeScript实现已保留于
供参考API 文档见
GitLab API 文档python-gitlab ：
官方文档FastMCP ：

框架文档

配置参考

环境变量 | 变量 | 必需 | 默认值 | 描述 | |----------|----------|---------|-------------| GITLAB_PERSONAL_ACCESS_TOKEN | 是 | - | GitLab API令牌 | GITLAB_API_URL | https://gitlab.com | 不 | | GitLab 实例 URL | GITLAB_PROJECT_ID | | 序号 | - | 默认项目ID | GITLAB_ALLOWED_PROJECT_IDS | | 序号 | - | 允许的项目ID（逗号分隔） | GITLAB_READ_ONLY_MODE | false | 编号 | | 启用只读模式 | GITLAB_DENIED_TOOLS_REGEX | | 编号 | - | 用于阻止特定工具的正则表达式 | USE_GITLAB_WIKI | true | 不是 | | 启用维基工具 | USE_MILESTONE | true | 编号 | | 启用里程碑工具 | USE_PIPELINE | true | 不 | | 启用管道工具 | SSE | false | 序号 | | 使用服务器发送事件传输 | STREAMABLE_HTTP | false | 不 | | 使用Streamable HTTP传输 | HOST | 127.0.0.1 | 编号 | | 服务器主机（SSE/HTTP 模式） | PORT | 8080 | 不（No）| | 服务器端口（SSE/HTTP 模式） | HTTP_PROXY | | 编号 | - | HTTP 代理 URL | HTTPS_PROXY | | 序号 | - | HTTPS 代理 URL | NO_PROXY | | 序号 | - | 代理绕过列表 | GITLAB_AUTH_COOKIE_PATH | | 编号 | - | Cookie 认证文件 | GITLAB_COMMIT_FILES_PER_PAGE | 20 | 不是 | | 设置分页大小 | LOG_LEVEL | INFO | 不 |

| 日志级别 |

运输方式

服务器支持以下优先级顺序的三种传输模式： 可流式传输的HTTP STREAMABLE_HTTP=true(如果
) - 最高优先级 上海证券交易所 SSE=true (如果 STREAMABLE_HTTP!=true并且
) - 中等优先级 stdio（标准输入输出库）

(默认) - 标准输入/输出

故障排除

常见问题问题 GITLAB_PERSONAL_ACCESS_TOKEN not set

# Solution: Set your token in .env file
echo "GITLAB_PERSONAL_ACCESS_TOKEN=glpat-xxxxxxxxxxxx" >> .env

**：**问题

# Solution: Use test token for unit tests
env GITLAB_PERSONAL_ACCESS_TOKEN=test_token uv run pytest tests/unit/

测试因认证错误而失败问题

# Solution: Reinstall dependencies
uv sync --reinstall

运行服务器时出现导入错误问题

# Solution: Run mypy with verbose output
uv run mypy src/ --verbose

类型检查错误

调试模式

LOG_LEVEL=DEBUG uv run python -m gitlab_mcp

启用调试日志以进行故障排除：

做出贡献

我们欢迎投稿！请遵循以下指南： 叉子
存储库 创建git checkout -b feature/amazing-feature一个特性分支（
）写
对你所做的更改进行测试 确保make all所有质量检查均通过（
) 提交（或：提交更改）
你的更改 推动
到你的分公司 开放

一个拉取请求

代码风格
遵循PEP 8（由Black和Ruff强制执行）
为所有函数使用类型提示
为公共API编写文档字符串
保持函数专注且可测试

保持清洁架构的界限

项目状态

当前实施情况 **✅**核心基础设施
完成 **✅**88个GitLab工具
已全面实施 **✅**清洁架构
实现了4层（功能/结构） **✅（对号，表示正确、同意或确认）**测试框架
240多个测试，覆盖率72% **✅**持续集成/持续交付（CI/CD）
GitHub Actions 工作流 **✅**Docker
生产就绪的容器 **✅（对号，表示正确、确认或完成）**文档

全面指南

路线图见 `MISSING_TOOLS_ROADMAP.md` 翻译为中文是：`缺失工具路线图.md`

以便未来进行增强。

许可证这个项目遵循MIT许可证授权——详见许可证

文件中有详细信息。

致谢 FastMCP
- 由@jlowin打造的现代MCP框架 python-gitlab（可译为“Python GitLab库”或“用于Python的GitLab接口”）
- 官方GitLab Python客户端 TypeScript 版本 old/ - 原始实现（保存在
目录) 清洁架构

- 受到罗伯特·马丁（Uncle Bob）架构原则的启发

使用Python和Clean Architecture精心打造报告错误 • 请求功能 •