13shivam/gitlab-mcp-server

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

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

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

Request Flow

The interaction sequence shows:

1. Initialization - Container setup, tool registration, validation
2. Request Processing - Entity extraction, content processing, rate limiting
3. Tool Execution - GitLab API calls, caching, response processing
4. Error Handling - Retry logic, error categorization, graceful degradation
5. 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:

1. Install dependencies: pip install -e .
2. Configure .env with your GitLab token from .env.example
3. 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

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

📄 License

MIT License