EGMA: Enhanced GitLab MCP API Server

A Model Context Protocol (MCP) server for GitLab integration, built with the official python-gitlab SDK. Provides AI assistants with intelligent GitLab access through 143+ specialized tools.

✨ Key Features

🔧 143+ Tools - Projects, issues, MRs, pipelines, search, repository operations
🧠 Smart Context - URL deduction, entity recognition, conversation continuity
🛡️ Secure - Read-only by default, configurable access control
⚡ Optimized - Caching, rate limiting, intelligent filtering
🔌 Compatible - Works with Claude Desktop, Amazon Q, Cursor, and other MCP clients

🛠 Tool Categories

Category	Tools	Description
Projects	24+	Smart search, activity scoring, context deduction
Issues	19+	Intelligent filtering, contextual search, URL deduction
Merge Requests	20+	Analysis, review assistant, conflict detection
Pipelines	19+	Health monitoring, failure troubleshooting, performance insights
Search	15+	Global search, code search, relevance scoring
Repository	16+	Branch analysis, commit insights, file operations
General	6+	Core GitLab operations with processing

🏗 Architecture

High Level View

The GitLab MCP Server follows a clean architecture pattern with clear separation of concerns:

AI Assistant Users interact through MCP clients (Claude Desktop, Amazon Q)
FastMCP Server handles MCP protocol communication
DI Container manages dependencies and service provisioning
Tool Registry provides 143+ specialized GitLab tools
Intelligence Layer enables context extraction and URL deduction
Processing Pipeline handles content preprocessing
Cache Layer optimizes API response performance

Layered View

The system is organized into distinct layers:

Client Layer - MCP clients (Claude Desktop, Amazon Q, etc.)
Entry Layer - FastMCP Server, Lifespan Manager, Signal Handlers
Core Layer - DI Container, Settings, Cache Manager, Rate Limiter
Service Layer - GitLab Client, Tool Registry, Content Pipeline
Intelligence Layer - Context Extractor, URL Deducer, Entity Matcher
Tool Layer - Project, Issue, MR, Pipeline Tools
Domain Layer - Content Context, GitLab Models, Error Handlers
External Layer - GitLab API v4

Request Flow

The interaction sequence shows:

Initialization - Container setup, tool registration, validation
Request Processing - Entity extraction, content processing, rate limiting
Tool Execution - GitLab API calls, caching, response processing
Error Handling - Retry logic, error categorization, graceful degradation
Health Monitoring - Connection testing, metrics collection

📦 Quick Start

Prerequisites

Docker
Amazon Q or Claude Chat Tool

{
  "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"
      ]
    }
  }
}

Prerequisites For Advanced Users

Python 3.10+
GitLab Personal Access Token with read_api and read_repository scopes

Installation

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 .

Alternative with UV (faster):

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

Configuration

Create .env file:

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

Required environment variables:

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

Optional configuration:

# 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

🚀 Usage

Start Server

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

MCP Client Configuration

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 Developer:

{
  "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"
    }
  }
}

🧠 Intelligence Features

Context Awareness

URL Deduction: Automatically extract project IDs, issue numbers, MR references from GitLab URLs
Entity Recognition: Parse project paths, user mentions, commit SHAs from conversation
Context Continuity: Remember project context across multiple tool calls
Smart Parameter Filling: Auto-complete missing parameters from conversation history

Natural Language Understanding

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

Intelligent Analysis

Relevance Scoring: Rank search results by relevance to user query
Health Monitoring: Proactive insights into pipeline health and project status
Trend Analysis: Identify patterns in CI/CD performance, issue resolution, etc.
Recommendations: Actionable suggestions based on data analysis

🔧 Development

Development Setup

With UV (Recommended):

# 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]"

With 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]"

Quick Setup:

Install dependencies: pip install -e .
Configure .env with your GitLab token from .env.example
Run server: python -m src.server

Testing

The project includes both unit tests and integration tests for comprehensive coverage.

Unit Tests

# 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

Integration Tests

The project includes comprehensive integration tests:

Run integration tests with:

# 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

🛡 Security & Configuration

Read-Only Mode

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

Environment-Specific Defaults:

Production: Always true (enforced for safety)
Development: false (allows write operations)
Testing: true (enforced for safety)

Advanced Configuration

# 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

🚨 Troubleshooting

Authentication Issues

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

Connection Problems

Verify GITLAB_URL is correct
Check network connectivity: ping gitlab.com
Ensure token has required scopes: read_api, read_repository
Set GITLAB_SSL_VERIFY=false for self-signed certificates

Server Health Monitoring

# 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()

🎯 Example Use Cases

Smart Issue Management

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

Intelligent MR Review

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

CI/CD Health Monitoring

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

Context-Aware Search

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

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Run the test suite: python mcp_integration_tests/test_runner.py
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

📄 License

MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.github		.github
assets		assets
docker		docker
mcp_integration_tests		mcp_integration_tests
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
uv.lock		uv.lock

13shivam/gitlab-mcp-server

Folders and files

Latest commit

History

Repository files navigation