Gitlab MCP 0044eb0b

MCPAI代理

提供方 nostoslabs

AI代理 stdio · 本地进程 Token 社区 / 第三方
查看接入方式

一个基于Python的GitLab集成MCP(模型上下文协议)服务器,提供88种工具与GitLab API交互,适用于GitLab项目管理、CI/CD流程和团队协作。

一句话选型结论

按资料字段整理

Gitlab MCP 0044eb0b 属于AI代理类 MCP 服务器,stdio · 本地进程,Token,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类AI代理 传输方式stdio · 本地进程 鉴权Token 部署方式本地部署
GitHub 星标 0 仓库热度,无公开仓库时显示未标注
工具数 19 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

AI代理
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量19暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

适用场景

GitLab集成Python本地部署Python服务器模型上下文协议项目管理CI/CD工具

安装与配置

stdio · 本地进程 Token
客户端在本机拉起子进程,数据不出本机
uv run python -m gitlab_mcp

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Python,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 19 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
给代理接外部能力

让代理在任务中途调用搜索、数据库等真实工具。

多步任务编排

把一串操作拆成步骤,由代理按顺序执行。

自动化重复流程

把固定流程交给代理跑,减少手工操作。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 19 个工具,覆盖面较广,能满足多种调用。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好Token对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在AI代理场景里让模型直接调用外部能力的人。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Gitlab MCP 0044eb0b当前 19 stdio · 本地进程 本地部署 有 2026-05-17
Filesystem 560c4363 13 未标注 本地部署 无 2026-05-17
Server Everything (everything) 11 stdio · 本地进程 本地部署 有 2026-05-17
Time 7365cb6d 2 SSE · 服务端推送 远程部署 有 2026-05-18
Everything Claude Code 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Openmemory 557e1585 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

AI代理
字段来自项目仓库与公开索引,中文说明由本站标注
提供方nostoslabs上游标注的维护方 nostoslabs
分类AI代理本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式Token远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Python本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

20.5 KB
来自项目仓库与上游目录的原文,未做删改

GitLab MCP Server

A Python-based MCP (Model Context Protocol) server for GitLab integration

Features •
Quick Start •
Documentation •
Development •
Architecture


Overview

GitLab MCP Server is a comprehensive Python implementation of the Model Context Protocol for GitLab, providing 88 tools to interact with GitLab's API. Built with Clean Architecture principles and the FastMCP framework, it offers type-safe, tested, and maintainable access to GitLab's full feature set.

Key Highlights

  • 88 GitLab Tools - Full feature parity with TypeScript implementation
  • Clean Architecture - 4-layer architecture for maintainability and testability
  • Type-Safe - Full type hints with mypy strict mode enforcement
  • Well-Tested - 240+ tests with 72% coverage
  • Production-Ready - Docker support, CI/CD pipelines, security scanning
  • Multiple Transports - stdio, SSE, and Streamable HTTP support

Features

GitLab Operations (88 Tools)

The server provides comprehensive GitLab API access across 19 categories:

Category Tools Description
Issues 6 Create, read, update, delete, and list issues
Merge Requests 9 Full MR lifecycle management including diffs
Projects 5 Project management and search
Pipelines 7 CI/CD pipeline operations and job management
Repository 4 File operations and repository tree navigation
Branches 3 Branch creation, deletion, and listing
Wikis 7 Wiki page management and attachments
Milestones 10 Milestone tracking and burndown charts
Labels 3 Label management and organization
Commits 2 Commit details and diffs
Discussions 2 Issue and MR discussions/threads
Users 1 User information retrieval
Members 1 Project member management
Namespaces 3 Namespace operations and verification
Groups 1 Group project listing
Jobs 2 Pipeline job control (play, cancel)
Issue Links 2 Issue relationship tracking
Draft Notes 0 (Planned - see roadmap)
Events 0 (Planned - see roadmap)

Architecture Features

  • Clean Architecture - Separation of concerns across 4 distinct layers
  • FastMCP Framework - Modern async-first MCP implementation
  • python-gitlab - Official GitLab Python client for API access
  • Pydantic - Data validation and settings management
  • Structured Logging - Production-ready logging with structlog
  • Retry Logic - Automatic retries with exponential backoff (tenacity)

Security & Quality

  • Read-Only Mode - Optional safety mode for production environments
  • Access Control - Project allowlist/denylist support
  • Tool Filtering - Regex-based tool access control
  • Type Safety - 100% mypy strict mode compliance
  • Security Scanning - Bandit static analysis and pip-audit
  • Pre-commit Hooks - Automatic code quality enforcement

Quick Start

Prerequisites

  • Python 3.11+ - Required for modern type hints and async features
  • uv - Fast Python package manager (recommended)
  • GitLab Personal Access Token - With appropriate API scopes

Installation```bash

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


### Configuration

Create a `.env` file with your GitLab credentials:```bash
# ============================================
# 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

Running the Server```bash

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


### Testing the Installation```bash
# Run all tests
make test

# Run tests with coverage report
make test-cov

# Run quality checks
make all

Architecture

GitLab MCP Server follows Clean Architecture principles with 4 distinct layers:```
┌─────────────────────────────────────────────────────────────┐
│ 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) │ │
│ └────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘


### Directory Structure```
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)

Development

Development Setup```bash

Install development dependencies

uv sync --dev

Install pre-commit hooks

uv run pre-commit install

Verify installation

make help


### Available Commands

The project includes a comprehensive Makefile for all development tasks:```bash
# 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

Quality Standards

All code must meet these standards before merging:

  • Linting: Zero ruff errors
  • Type Checking: Zero mypy errors
  • Formatting: Black-formatted code
  • Testing: All tests passing
  • Coverage: Maintain 70%+ overall coverage

Testing Strategy

The project follows Test-Driven Development (TDD) with three test layers:```bash

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


**Coverage Targets by Layer:**

- Domain Layer: 100% (pure business logic)
- Application Layer: 90%+ (use cases)
- Infrastructure Layer: 80%+ (external integrations)
- Presentation Layer: 85%+ (MCP tools)

### Adding New Tools

To add a new GitLab tool, follow the IMPLEMENTATION_GUIDE.md:

1. **Domain**: Create entity if needed (e.g., `Issue`, `MergeRequest`)
2. **Application**: Create use case with tests (e.g., `CreateIssueUseCase`)
3. **Infrastructure**: Implement repository method for API calls
4. **Presentation**: Create Pydantic schema and MCP tool handler
5. **Testing**: Write unit, integration, and e2e tests
6. **Documentation**: Update tool catalog and API docs

### Pre-commit Hooks

The project uses pre-commit hooks to enforce quality:

- Trailing whitespace removal
- End-of-file fixer
- YAML validation
- Large file check
- Black formatting
- Ruff linting
- Mypy type checking
- Bandit security scanning```bash
# Run manually
uv run pre-commit run --all-files

Docker Deployment

Building the Image```bash

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 .


### Running with Docker```bash
# 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 Compose```bash

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


The Docker image uses:
- **Multi-stage build** for minimal size
- **Chainguard Python base** for security
- **Health checks** for container monitoring
- **Non-root user** for security (planned)

---

## CI/CD

### GitHub Actions Workflows

The project includes 5 automated workflows:

1. **CI** (`.github/workflows/ci.yml`)
   - Code quality checks (black, ruff, mypy)
   - Test execution with coverage
   - Security scanning (bandit, pip-audit)
   - Codecov integration

2. **CodeQL** (`.github/workflows/codeql.yml`)
   - Security vulnerability scanning
   - Code quality analysis

3. **Docker Publish** (`.github/workflows/docker-publish.yml`)
   - Automated Docker image builds
   - Push to container registry

4. **Release** (`.github/workflows/release.yml`)
   - Automated version tagging
   - Release notes generation

5. **SonarCloud** (`.github/workflows/sonarcloud.yml`)
   - Code quality metrics
   - Technical debt tracking

### Running CI Locally```bash
# Run the same checks as CI
make all

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

Documentation

Comprehensive documentation is available in the docs/ directory:

Document Description
ARCHITECTURE.md Clean Architecture principles and layer details
IMPLEMENTATION_GUIDE.md Step-by-step guide for implementing tools
TESTING_GUIDE.md TDD approach and testing patterns
QUICK_REFERENCE.md Code templates and quick snippets
MISSING_TOOLS_ROADMAP.md Future tool implementation plan

Additional Resources

  • TypeScript Reference: The original TypeScript implementation is preserved in old/ for reference
  • API Documentation: See GitLab API Docs
  • python-gitlab: Official Documentation
  • FastMCP: Framework Documentation

Configuration Reference

Environment Variables

Variable Required Default Description
GITLAB_PERSONAL_ACCESS_TOKEN Yes - GitLab API token
GITLAB_API_URL No https://gitlab.com GitLab instance URL
GITLAB_PROJECT_ID No - Default project ID
GITLAB_ALLOWED_PROJECT_IDS No - Allowed project IDs (comma-separated)
GITLAB_READ_ONLY_MODE No false Enable read-only mode
GITLAB_DENIED_TOOLS_REGEX No - Regex to block specific tools
USE_GITLAB_WIKI No true Enable wiki tools
USE_MILESTONE No true Enable milestone tools
USE_PIPELINE No true Enable pipeline tools
SSE No false Use Server-Sent Events transport
STREAMABLE_HTTP No false Use Streamable HTTP transport
HOST No 127.0.0.1 Server host (SSE/HTTP modes)
PORT No 8080 Server port (SSE/HTTP modes)
HTTP_PROXY No - HTTP proxy URL
HTTPS_PROXY No - HTTPS proxy URL
NO_PROXY No - Proxy bypass list
GITLAB_AUTH_COOKIE_PATH No - Cookie authentication file
GITLAB_COMMIT_FILES_PER_PAGE No 20 Commit pagination size
LOG_LEVEL No INFO Logging level

Transport Modes

The server supports three transport modes with the following priority:

  1. Streamable HTTP (if STREAMABLE_HTTP=true) - Highest priority
  2. SSE (if SSE=true and STREAMABLE_HTTP!=true) - Medium priority
  3. stdio (default) - Standard input/output

Troubleshooting

Common Issues

Issue: `GITLAB_PERSONAL_ACCESS_TOKEN not set````bash

Solution: Set your token in .env file

echo "GITLAB_PERSONAL_ACCESS_TOKEN=glpat-xxxxxxxxxxxx" >> .env


**Issue**: Tests failing with authentication errors```bash
# Solution: Use test token for unit tests
env GITLAB_PERSONAL_ACCESS_TOKEN=test_token uv run pytest tests/unit/

Issue: Import errors when running the server```bash

Solution: Reinstall dependencies

uv sync --reinstall


**Issue**: Type checking errors```bash
# Solution: Run mypy with verbose output
uv run mypy src/ --verbose

Debug Mode

Enable debug logging for troubleshooting:bash LOG_LEVEL=DEBUG uv run python -m gitlab_mcp


Contributing

We welcome contributions! Please follow these guidelines:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Write tests for your changes
  4. Ensure all quality checks pass (make all)
  5. Commit your changes
  6. Push to your branch
  7. Open a Pull Request

Code Style

  • Follow PEP 8 (enforced by Black and Ruff)
  • Use type hints for all functions
  • Write docstrings for public APIs
  • Keep functions focused and testable
  • Maintain Clean Architecture boundaries

Project Status

Current Implementation

  • ✅ Core Infrastructure: Complete
  • ✅ 88 GitLab Tools: Fully implemented
  • ✅ Clean Architecture: 4 layers implemented
  • ✅ Testing Framework: 240+ tests, 72% coverage
  • ✅ CI/CD: GitHub Actions workflows
  • ✅ Docker: Production-ready containers
  • ✅ Documentation: Comprehensive guides

Roadmap

See MISSING_TOOLS_ROADMAP.md for future enhancements.


License

This project is licensed under the MIT License - see the LICENSE file for details.


Acknowledgments

  • FastMCP - Modern MCP framework by @jlowin
  • python-gitlab - Official GitLab Python client
  • TypeScript Version - Original implementation (preserved in old/ directory)
  • Clean Architecture - Inspired by Uncle Bob's architecture principles

Made with ❤️ using Python and Clean Architecture

Report Bug •
Request Feature •
Documentation

常见问题

7 问
答案由本站依据条目字段整理,不引用上游原文
Gitlab MCP 0044eb0b 怎么安装?

在客户端按下面的安装命令接入:uv run python -m gitlab_mcp。装完在客户端配置里引用同一个包或端点。

Gitlab MCP 0044eb0b 怎么在客户端里配置?

它的传输方式未标注,在客户端 MCP 配置里按官方文档填写启动命令和参数,保存后重启客户端生效。

Gitlab MCP 0044eb0b 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Gitlab MCP 0044eb0b 需要 API Key 吗?

资料标注需要Token认证,使用前准备好对应凭据,并按最小权限配置。

Gitlab MCP 0044eb0b 能提供哪些能力?

资料显示约 19 个工具;能力标签包括 GitLab集成、Python、Python服务器、项目管理。具体工具清单以官方文档为准。

Gitlab MCP 0044eb0b 需要什么运行环境?

运行时为 Python;属于本地进程,需要在本机装好运行环境。

Gitlab MCP 0044eb0b 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。