GitLab MCP Server

An MCP (Model Context Protocol) server for integrating GitLab with AI assistants like Cursor, ChatGPT, and any polymcp-compatible client. Manage merge requests, analyze CI/CD pipelines, create ADR documents, and more.

What it does

This project exposes GitLab APIs through the MCP protocol, allowing AI assistants to:

• List and manage merge requests
• Analyze failed pipeline jobs with fix suggestions
• Create ADR (Architecture Decision Records) documents in markdown
• View CI/CD job logs
• Trigger pipelines and retry failed jobs
• Deploy to AWS, Azure, and GCP

Requirements

• Python 3.8 or higher
• PolyMCP (for AI agent integration)
• FastAPI and uvicorn (for HTTP server)

Installation

git clone https://github.com/poly-mcp/Gitlab-MCP-Server.git
cd Gitlab-MCP-Server

pip install -r requirements.txt

Contents of requirements.txt:

fastapi>=0.104.0
uvicorn>=0.24.0
aiohttp>=3.9.0
pyyaml>=6.0
docstring-parser>=0.15
python-dotenv>=1.0.0
pydantic>=2.0.0
pip install polymcp==1.2.4

Configuration

Create a .env file in the project root:

# For use with real GitLab
GITLAB_BASE_URL=https://gitlab.com/api/v4
GITLAB_TOKEN=glpat-xxxxxxxxxxxx
GITLAB_PROJECT_ID=12345678

# Optional - security settings
SAFE_MODE=true
DRY_RUN=false

Usage with PolyMCP

This server is fully compatible with the polymcp library. Here is how to use it:

1. Start the server

# Production mode (requires token)
python gitlab_mcp_server.py --http --port 8000

2. Connect with polymcp

Create a file gitlab_chat.py:

#!/usr/bin/env python3
"""GitLab MCP Chat with PolyMCP"""
import asyncio
from polymcp.polyagent import UnifiedPolyAgent, OllamaProvider

async def main():
    # Configure the LLM provider (you can use OpenAI, Anthropic, Ollama, etc.)
    llm = OllamaProvider(model="gpt-oss:120b-cloud", temperature=0.1)
    
    # Point to the GitLab MCP server
    mcp_servers = ["http://localhost:8000/mcp"]
    
    agent = UnifiedPolyAgent(
        llm_provider=llm, 
        mcp_servers=mcp_servers,  
        verbose=True
    )
    
    async with agent:
        print("\nGitLab MCP Server connected!\n")
        print("Available commands:")
        print("- 'show me open merge requests'")
        print("- 'analyze failed jobs'")
        print("- 'create an ADR for cloud migration'")
        print("- 'exit' to quit\n")
        
        while True:
            user_input = input("\nYou: ")
            
            if user_input.lower() in ['exit', 'quit']:
                print("Session ended.")
                break
            
            result = await agent.run_async(user_input, max_steps=5)
            print(f"\nGitLab Assistant: {result}")

if __name__ == "__main__":
    asyncio.run(main())

3. Run it

python gitlab_chat.py

Example session:

GitLab MCP Server connected!

You: show me open merge requests in project mygroup/myproject

GitLab Assistant: I found 3 open merge requests:

1. MR !42 - "Fix authentication bug" 
   Author: john_doe
   Branch: bugfix/auth -> main
   
2. MR !43 - "Add caching layer"
   Author: jane_smith  
   Branch: feature/cache -> main

3. MR !44 - "Update dependencies"
   Author: bob_wilson
   Branch: chore/deps -> main

You: analyze why the pipeline is failing

GitLab Assistant: I analyzed pipeline #12345. There are 2 failed jobs:

1. test:unit (stage: test)
   Error: Snapshot test mismatch
   Suggestion: Run 'npm test -- -u' to update snapshots

2. security:sonar (stage: security)
   Error: Code coverage below threshold (67% < 80%)
   Suggestion: Add tests for uncovered functions

You: exit
Session ended.

Usage with Cursor

Method 1 - Direct import

Copy cursor_tools.py to your project and use it directly:

from cursor_tools import *

# List merge requests
mrs = list_open_merge_requests("mygroup/myproject")

# Analyze pipeline
analysis = analyze_pipeline_failures("mygroup/myproject")

# Create ADR
adr = create_architecture_decision(
    title="Kubernetes Adoption",
    context="We need to scale horizontally",
    decision="We will migrate to Kubernetes on GKE",
    consequences="Higher operational complexity but better scalability"
)

Method 2 - MCP Configuration

Add to .cursor/mcp_config.json:

{
  "mcpServers": {
    "gitlab": {
      "command": "python",
      "args": ["gitlab_mcp_server.py", "--mode", "stdio"]
    }
  }
}

Usage with ChatGPT

1. Start the server and expose it publicly (with ngrok or similar):

python gitlab_mcp_server.py --http --port 8000
ngrok http 8000

2. Create a Custom GPT with Actions pointing to the ngrok URL

3. Or use Code Interpreter by uploading gitlab_assistant.py

Safety Features

The server includes built-in protections:

Feature	Default	What it does
Safe Mode	ON	Blocks write operations until you're ready
Dry Run	OFF	Test operations without executing them
Project Allowlist	* (all allowed)	Use * for all, empty to block all, or list specific projects
Rate Limiting	60/min	Prevents API abuse

💡 Start with SAFE_MODE=true to explore safely, then disable when needed.

Available Tools

Merge Request Management

Tool	Description
list_merge_requests	List merge requests with filters (state, author, assignee)
get_merge_request_details	Get MR details including changes and discussions
create_merge_request	Create a new merge request
approve_merge_request	Approve a merge request
merge_merge_request	Merge a merge request into target branch
rebase_merge_request	Rebase a merge request onto target branch

Code Search

Tool	Description
search_code	Search for code across project files

Pipeline & CI/CD

Tool	Description
list_pipeline_jobs	List all jobs in a pipeline with status
get_job_log	Get the log output of a specific job
analyze_failed_jobs	Analyze failures and suggest fixes
trigger_pipeline	Trigger a new pipeline run
retry_pipeline	Retry all failed jobs in a pipeline
cancel_pipeline	Cancel a running pipeline
retry_failed_job	Retry a specific failed job

ADR (Architecture Decision Records)

Tool	Description
create_adr_document	Create an ADR document in Markdown format
commit_adr_to_gitlab	Commit ADR to repository with optional MR

Cloud Deployment

Tool	Description
deploy_to_cloud	Deploy to AWS, Azure, or GCP via pipeline

Security

To use the server safely with Cursor or other AI assistants:

1. Create a GitLab token with minimal permissions (only read_api and read_repository)
2. Enable SAFE_MODE=true in the .env file to disable destructive operations
3. Use DRY_RUN=true to simulate operations without executing them
4. Limit accessible projects by configuring ALLOWED_PROJECTS

The server tracks all operations and provides usage statistics.

Project Structure

Gitlab-MCP-Server/
├── gitlab_mcp_server.py    # Main server
├── cursor_tools.py         # Wrapper for Cursor
├── gitlab_chat.py          # Client for PolyMCP
├── gitlab_assistant.py     # Client for ChatGPT
├── .env.example            # Configuration template
├── requirements.txt        # Dependencies
└── README.md

Troubleshooting

Error	Solution
GITLAB_TOKEN is required	Create .env file with your token
Operation blocked by safe mode	Set SAFE_MODE=false in .env
Access denied to project	Check token permissions or ALLOWED_PROJECTS
Request timed out	Increase MAX_RETRIES in .env

Contributing

Contributions are welcome. Open an issue to discuss significant changes before proceeding with a pull request.

License

MIT License - see LICENSE file for details.

Useful Links

• GitLab API Documentation: https://docs.gitlab.com/ee/api/
• Model Context Protocol: https://modelcontextprotocol.io/
• PolyMCP: https://github.com/poly-mcp/polymcp