GitLab MCP Server

Connect your AI assistant to GitLab. Ask questions like "List open merge requests", "Show me reviews for MR #123", "Get commit discussions for MR #456", or "Find merge requests for the feature branch" directly in your chat.

Table of Contents

• Quick Setup
• What You Can Do
• Configuration Options
• Troubleshooting
• Tool Reference
• Development
• Security Notes
• Support

Quick Setup

Prerequisites

This project uses uv for fast and reliable Python package management.

Install uv:

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or with pip
pip install uv

Installation

1. Install the server:

   git clone https://github.com/amirsina-mandegari/gitlab-mcp-server.git
   cd gitlab-mcp-server
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv pip install -e .
   chmod +x run-mcp.sh
   

2. Get your GitLab token:

   • Go to GitLab → Settings → Access Tokens
   • Create token with read_api scope
   • Copy the token

3. Configure your project: In your project directory, create gitlab-mcp.env:

   GITLAB_PROJECT_ID=12345
   GITLAB_ACCESS_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
   GITLAB_URL=https://gitlab.com
   

4. Connect to Cursor: Create .cursor/mcp.json in your project:

   {
     "mcpServers": {
       "gitlab-mcp": {
         "command": "/path/to/gitlab-mcp-server/run-mcp.sh",
         "cwd": "/path/to/your-project"
       }
     }
   }
   

5. Restart Cursor and start asking GitLab questions!

What You Can Do

Once connected, try these commands in your chat:

• "List open merge requests"
• "Show me details for merge request 456"
• "Get reviews and discussions for MR #123"
• "Show me the test summary for MR #456"
• "What tests failed in merge request #789?"
• "Show me the pipeline for MR #456"
• "Get the failed job logs for merge request #789"
• "Show me commit discussions for MR #456"
• "Get all comments on commits in merge request #789"
• "Find merge requests for the feature/auth-improvements branch"
• "Show me closed merge requests targeting main"
• "Reply to discussion abc123 in MR #456 with 'Thanks for the feedback!'"
• "Create a new review comment in MR #789 asking about the error handling"
• "Resolve discussion def456 in MR #123"

Working with Review Comments

The enhanced review tools allow you to interact with merge request discussions:

1. First, get the reviews to see discussion IDs:

   "Show me reviews for MR #123"
   

2. Reply to specific discussions using the discussion ID:

   "Reply to discussion abc123 in MR #456 with 'I'll fix this in the next commit'"
   

3. Create new discussion threads to start conversations:

   "Create a review comment in MR #789 asking 'Could you add error handling here?'"
   

4. Resolve discussions when issues are addressed:

   "Resolve discussion def456 in MR #123"
   

Note: The get_merge_request_reviews tool now displays discussion IDs and note IDs in the output, making it easy to reference specific discussions when replying or resolving.

Working with Test Reports (Recommended for Test Failures)

GitLab provides two tools for checking test results - use the summary for quick checks, and the full report for detailed debugging:

Option 1: Test Summary (Fast & Lightweight) ⚡

Use get_pipeline_test_summary for a quick overview:

"Show me the test summary for MR #123"
"How many tests passed in MR #456?"

What You Get:

• 📊 Pass/fail counts per test suite
• ⏱️ Total execution time
• 🎯 Pass rate percentage
• ⚡ Fast - doesn't include detailed error messages

Option 2: Full Test Report (Detailed) 🔍

Use get_merge_request_test_report for detailed debugging:

"Show me the test report for MR #123"
"What tests failed in merge request #456?"

What You Get:

• ✅ Specific test names that passed/failed
• ❌ Error messages and stack traces
• 📦 Test suites organized by class/file
• ⏱️ Execution time for each test
• 📊 Pass rate and summary statistics
• 📄 File paths and line numbers

How Both Work:

• Automatically fetch the latest pipeline for the merge request
• Retrieve test data from that pipeline (uses GitLab's /pipelines/:pipeline_id/test_report or /test_report_summary API)

Example Output:

Test Report Summary:
Total: 45 tests | ✅ 42 passed | ❌ 3 failed | Pass Rate: 93.3%

❌ Failed Tests:
  test_login_with_invalid_password (0.3s)
    Error: AssertionError: Expected 401, got 200
    File: tests/auth_test.py

Why Use This Instead of Job Logs?

• 🎯 No noise: Only test results, no build/setup output
• 📊 Structured data: Easy for AI to understand and suggest fixes
• 🚀 Fast: Much smaller than full job logs
• 🔍 Precise: Shows exact test names and error locations

Requirements:

Your CI must upload test results using artifacts:reports:junit in .gitlab-ci.yml:

test:
  script:
    - pytest --junitxml=report.xml
  artifacts:
    reports:
      junit: report.xml

Working with Pipeline Jobs and Logs

The pipeline tools provide a two-step workflow for debugging test failures:

Step 1: Get Pipeline Overview

Use get_merge_request_pipeline to see all jobs and their statuses:

"Show me the pipeline for MR #456"

What You Get:

• Pipeline overview (status, duration, coverage)
• All jobs grouped by status (failed, running, success)
• Job IDs for each job (use these to fetch logs)
• Direct links to view jobs in GitLab
• Job-level timing and stage information

Step 2: Get Specific Job Logs

Use get_job_log with a job ID to fetch the actual output:

"Get the log for job 12345"
"Show me the output of job 67890"

What You Get:

• Complete job output/trace
• Log size and line count
• Automatically truncated to last 15,000 characters for very long logs

Typical Workflow:

You: "Show me the pipeline for MR #123"
AI: "Pipeline failed. 2 jobs failed:
     - test-unit (Job ID: 12345)
     - test-integration (Job ID: 67890)"

You: "Get the log for job 12345"
AI: [Shows full test output with error details]

You: "Fix the failing test"
AI: [Analyzes the log and suggests fixes]

Why Two Tools?

• Performance: Only fetch logs when needed (not all at once)
• Flexibility: Check any job's log (failed, successful, or running)
• Context Efficient: Avoid dumping huge logs unnecessarily

Working with Commit Discussions

The get_commit_discussions tool provides comprehensive insights into discussions and comments on individual commits within a merge request:

1. View all commit discussions for a merge request:

   "Show me commit discussions for MR #123"
   

2. Get detailed commit conversation history:

   "Get all comments on commits in merge request #456"
   

This tool is particularly useful for:

• Code Review Tracking: See all feedback on specific commits
• Discussion History: Understand the evolution of code discussions
• Commit-Level Context: View comments tied to specific code changes
• Review Progress: Monitor which commits have been discussed

Technical Implementation:

• Uses /projects/:project_id/merge_requests/:merge_request_iid/commits to get all commits with proper pagination
• Fetches ALL merge request discussions using /projects/:project_id/merge_requests/:merge_request_iid/discussions with pagination support
• Filters discussions by commit SHA using position data to show commit-specific conversations
• Handles both individual comments and discussion threads correctly

The output includes:

• Summary of total commits and discussion counts
• Individual commit details (SHA, title, author, date)
• All discussions and comments for each commit with file positions
• Complete conversation threads with replies
• File positions for diff-related comments
• Thread conversations with replies

Configuration Options

Project-Level (Recommended)

Each project gets its own gitlab-mcp.env file with its own GitLab configuration. Keep tokens out of version control.

Global Configuration

Set environment variables system-wide instead of per-project:

export GITLAB_PROJECT_ID=12345
export GITLAB_ACCESS_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
export GITLAB_URL=https://gitlab.com

Find Your Project ID

• Go to your GitLab project → Settings → General → Project ID
• Or check the URL: https://gitlab.com/username/project (use the numeric ID)

Troubleshooting

Authentication Error: Verify your token has read_api permissions and is not expired.

Project Not Found: Double-check your project ID is correct (it's a number, not the project name).

Connection Issues: Make sure your GitLab URL is accessible and correct.

Script Not Found: Ensure the path in your MCP config points to the actual server location and the script is executable.

Tool Reference

Migrating from pip to uv

If you have an existing installation using pip, here's how to migrate to uv:

1. Install uv (see Prerequisites section above)

2. Remove the old virtual environment:

   deactivate  # If you have a venv activated
   rm -rf .venv
   

3. Create a new virtual environment with uv:

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv pip install -e .
   

4. For development, install dev dependencies:

   uv pip install -e ".[dev]"
   

That's it! Your project is now using uv for faster and more reliable dependency management.

Note: The requirements.txt and dev-requirements.txt files are kept for backward compatibility. However, pyproject.toml is now the source of truth for dependencies. If you add new dependencies, update pyproject.toml and regenerate the requirements files if needed:

uv pip compile pyproject.toml -o requirements.txt
uv pip compile --extra dev pyproject.toml -o dev-requirements.txt

Development

Project Structure

gitlab-mcp-server/
├── main.py              # MCP server entry point
├── config.py            # Configuration management
├── gitlab_api.py        # GitLab API client
├── utils.py             # Utility functions
├── logging_config.py    # Logging configuration
├── run-mcp.sh          # Launch script
└── tools/              # Tool implementations package
    ├── __init__.py         # Package initialization
    ├── list_merge_requests.py
    ├── get_merge_request_details.py
    ├── get_merge_request_test_report.py
    ├── get_pipeline_test_summary.py
    ├── get_merge_request_pipeline.py
    ├── get_job_log.py
    ├── get_merge_request_reviews.py
    ├── get_commit_discussions.py
    ├── get_branch_merge_requests.py
    └── reply_to_review_comment.py

Adding Tools

1. Create new file in tools/ directory
2. Add import and export to tools/__init__.py
3. Add to list_tools() in main.py
4. Add handler to call_tool() in main.py

Development Setup

1. Install development dependencies:

uv pip install -e ".[dev]"

2. Set up pre-commit hooks:

pre-commit install

This will automatically check and format your code for:

• ✨ Trailing whitespace - auto-removed
• 📄 End-of-file issues - auto-fixed
• 🎨 Code formatting (black) - auto-formatted
• 📦 Import sorting (isort) - auto-organized
• 🐍 Python style (flake8) - linted with bugbear & print detection
• 🔒 Security issues (bandit) - security checks
• 📋 YAML/JSON formatting - validated

3. Format all existing code (first time only):

# Install dependencies first if not already done
uv pip install -e ".[dev]"

# Format everything
black --line-length=120 .
isort --profile black --line-length=120 .

4. Run pre-commit manually on all files:

pre-commit run --all-files

Testing

python test_tools.py

Security Notes

• Add gitlab-mcp.env to your .gitignore
• Never commit access tokens
• Use project-specific tokens with minimal permissions
• Rotate tokens regularly

Support

• Check GitLab API documentation
• Open issues at github.com/amirsina-mandegari/gitlab-mcp-server

License

MIT License - see LICENSE file for details.