GitLab MR MCP

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.

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

Quick Setup

Installation

# Using pipx (recommended)
pipx install gitlab-mr-mcp

# Or using uv
uv tool install gitlab-mr-mcp

# Or using pip
pip install gitlab-mr-mcp

Note: Using pipx or uv tool is recommended as they automatically add the gitlab-mcp command to your PATH. If using pip install, ensure your Python scripts directory is in PATH, or use the full path to the command.

Get your GitLab token

Go to GitLab → Settings → Access Tokens
Create token with read_api scope (add api scope if you want write access)
Copy the token

Configure your MCP client

Multi-Project Setup (Recommended)

For working with multiple GitLab projects, add to your global MCP config (~/.cursor/mcp.json for Cursor):

{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "gitlab-mcp",
      "env": {
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

This single configuration works across all your projects. Use search_projects or list_my_projects to find project IDs, then specify project_id in your requests.

Single-Project Setup

For working with a single project, you can set a default project ID:

{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "gitlab-mcp",
      "env": {
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_PROJECT_ID": "12345"
      }
    }
  }
}

Restart your MCP client and start asking GitLab questions!

What You Can Do

Once connected, try these commands in your chat:

Multi-Project Workflow

"What projects do I have access to?"
"Search for the backend project"
"Show open MRs for project 12345"
"List merge requests for group/my-project"

Single-Project Commands

"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"
"Approve merge request #456"
"Merge MR #123 with squash"
"Merge MR #789 when pipeline succeeds"

Working with Review Comments

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

First, get the reviews to see discussion IDs:
```
"Show me reviews for MR #123"
```

Reply to specific discussions using the discussion ID:

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

Create new discussion threads to start conversations:

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

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.

Approving and Merging

Complete the MR lifecycle with approval and merge tools:

Approve a merge request:
```
"Approve MR #123"
```

Merge with options:

"Merge MR #456 with squash"
"Merge MR #789 and remove source branch"
"Merge MR #123 when pipeline succeeds"

Revoke approval (if needed):
```
"Unapprove MR #456"
```

Merge Options:

squash - Squash commits into a single commit
should_remove_source_branch - Delete source branch after merge
merge_when_pipeline_succeeds - Auto-merge when pipeline passes
sha - Ensure HEAD hasn't changed (safety check)

Note: You cannot approve your own MRs. The merge will fail if the MR has conflicts, is in draft status, or doesn't meet approval requirements.

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:

## Summary

**Total**: 45 | **Passed**: 42 | **Failed**: 3 | **Errors**: 0
**Pass Rate**: 93.3%

## Failed Tests

### [FAIL] test_login_with_invalid_password

**Duration**: 0.300s
**Class**: `tests.auth_test.TestAuth`

**Error Output**:
AssertionError: Expected 401, got 200

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:

View all commit discussions for a merge request:
```
"Show me commit discussions for MR #123"
```

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

MCP Config (Recommended)

Configure environment variables directly in your MCP client config as shown in Quick Setup. This keeps project-specific settings with the project.

Environment Variables

Alternatively, set environment variables in your shell:

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

SOCKS Proxy Support

Route all GitLab API requests through a SOCKS5 proxy by setting SOCKS_PROXY:

{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "gitlab-mcp",
      "env": {
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_PROJECT_ID": "12345",
        "SOCKS_PROXY": "socks5://127.0.0.1:1080"
      }
    }
  }
}

Or via environment variable:

export SOCKS_PROXY=socks5://127.0.0.1:1080

When SOCKS_PROXY is not set, connections are made directly (no proxy).

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

Project Discovery Tools

Tool	Description	Parameters
`search_projects`	Primary - Fast search by name (use this first)	`search`, `membership`, `limit`
`list_my_projects`	List all projects (slower, use for browsing)	`owned`, `limit`

Merge Request Tools

All project-scoped tools accept an optional project_id parameter. If not provided, falls back to GITLAB_PROJECT_ID env var.

Tool	Description	Parameters
`list_merge_requests`	List merge requests	`project_id`, `state`, `target_branch`, `limit`
`get_merge_request_details`	Get MR details	`project_id`, `merge_request_iid`
`create_merge_request`	Create a new merge request	`project_id`, `source_branch`, `target_branch`, `title`...
`update_merge_request`	Update an existing merge request	`project_id`, `merge_request_iid`, `title`, `assignees`...
`merge_merge_request`	Merge an MR	`project_id`, `merge_request_iid`, `squash`, `sha`...
`approve_merge_request`	Approve an MR	`project_id`, `merge_request_iid`, `sha`
`unapprove_merge_request`	Revoke approval from an MR	`project_id`, `merge_request_iid`
`get_pipeline_test_summary`	Get test summary (fast overview)	`project_id`, `merge_request_iid`
`get_merge_request_test_report`	Get detailed test failure reports	`project_id`, `merge_request_iid`
`get_merge_request_pipeline`	Get pipeline with all jobs	`project_id`, `merge_request_iid`
`get_job_log`	Get trace/output for specific job	`project_id`, `job_id`
`get_merge_request_reviews`	Get reviews/discussions	`project_id`, `merge_request_iid`
`get_commit_discussions`	Get discussions on commits	`project_id`, `merge_request_iid`
`get_branch_merge_requests`	Find MRs for branch	`project_id`, `branch_name`
`reply_to_review_comment`	Reply to existing discussion	`project_id`, `merge_request_iid`, `discussion_id`, `body`
`create_review_comment`	Create new discussion thread	`project_id`, `merge_request_iid`, `body`
`resolve_review_discussion`	Resolve/unresolve discussion	`project_id`, `merge_request_iid`, `discussion_id`
`list_project_members`	List project members	`project_id`
`list_project_labels`	List project labels	`project_id`

Roadmap

Recently Added

v1.4.0: Project discovery tools, MCP best practices (tool titles, annotations), improved prompts
v1.3.1: Fixed multi-workspace environment variable conflict in Cursor
v1.3.0: SOCKS5 proxy support for routing GitLab API requests
v1.2.0: Merge, approve, and unapprove MR tools - complete MR lifecycle
v1.1.0: Create and update MR tools, cleaner output formatting

Coming Next

Issue Management - List, create, update issues and add comments
Inline Comments - Add code review comments on specific lines

Considering

Lightweight file list for MRs (changed files without full diff)
Rebase MR via API

Out of Scope

Branch operations, file content fetching, and full diffs are intentionally not included - use git locally for these tasks, it's faster and more capable.

Have a feature request? Open an issue!

Development

Project Structure

gitlab_mr_mcp/
├── __init__.py          # Package version
├── __main__.py          # Entry point for python -m
├── server.py            # MCP server implementation
├── config.py            # Configuration management
├── gitlab_api.py        # GitLab API client
├── utils.py             # Utility functions
├── logging_config.py    # Logging configuration
└── tools/               # Tool implementations
    ├── __init__.py
    ├── list_merge_requests.py
    ├── get_merge_request_details.py
    ├── create_merge_request.py
    ├── update_merge_request.py
    └── ... (more tools)

Adding Tools

Create new file in gitlab_mr_mcp/tools/ directory
Add import and export to gitlab_mr_mcp/tools/__init__.py
Add to list_tools() in gitlab_mr_mcp/server.py
Add handler to call_tool() in gitlab_mr_mcp/server.py

Adding Prompts

Prompts provide workflow guidance to AI assistants. Add new prompts in gitlab_mr_mcp/prompts.py:

Define the prompt content as a string constant
Add entry to the PROMPTS dictionary with title, description, and content

NEW_PROMPT = """
Your prompt content here - focus on decision trees and when to use which tool.
"""

PROMPTS = {
    # ... existing prompts ...
    "new-prompt": {
        "title": "Human Readable Title",
        "description": "Short description for prompt list",
        "content": NEW_PROMPT,
    },
}

Development Setup

Install development dependencies:

make install
# or: uv pip install -e ".[dev]"

Available make commands:

make install   # Install in editable mode with dev deps
make dev       # Build and install wheel locally
make test      # Run tests
make lint      # Run linters
make format    # Format code
make check     # Lint + test
make clean     # Remove build artifacts

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

Format all existing code (first time only):

make format
# or: black --line-length=120 . && isort --profile black --line-length=120 .

Run pre-commit manually on all files:

pre-commit run --all-files

Running Tests

make test
# or: uv run pytest tests/ -v

Security Notes

Never commit access tokens to version control
Use project-specific tokens with minimal permissions (read_api scope)
Rotate tokens regularly
Store tokens in your MCP config (which should not be committed)

Support

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

License

MIT License - see LICENSE file for details.

GitLab MR MCP

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

Quick Setup

Installation

# Using pipx (recommended)
pipx install gitlab-mr-mcp

# Or using uv
uv tool install gitlab-mr-mcp

# Or using pip
pip install gitlab-mr-mcp

Note: Using pipx or uv tool is recommended as they automatically add the gitlab-mcp command to your PATH. If using pip install, ensure your Python scripts directory is in PATH, or use the full path to the command.

Get your GitLab token

Go to GitLab → Settings → Access Tokens
Create token with read_api scope (add api scope if you want write access)
Copy the token

Configure your MCP client

Multi-Project Setup (Recommended)

For working with multiple GitLab projects, add to your global MCP config (~/.cursor/mcp.json for Cursor):

{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "gitlab-mcp",
      "env": {
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

This single configuration works across all your projects. Use search_projects or list_my_projects to find project IDs, then specify project_id in your requests.

Single-Project Setup

For working with a single project, you can set a default project ID:

{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "gitlab-mcp",
      "env": {
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_PROJECT_ID": "12345"
      }
    }
  }
}

Restart your MCP client and start asking GitLab questions!

What You Can Do

Once connected, try these commands in your chat:

Multi-Project Workflow

"What projects do I have access to?"
"Search for the backend project"
"Show open MRs for project 12345"
"List merge requests for group/my-project"

Single-Project Commands

"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"
"Approve merge request #456"
"Merge MR #123 with squash"
"Merge MR #789 when pipeline succeeds"

Working with Review Comments

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

First, get the reviews to see discussion IDs:
```
"Show me reviews for MR #123"
```

Reply to specific discussions using the discussion ID:

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

Create new discussion threads to start conversations:

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

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.

Approving and Merging

Complete the MR lifecycle with approval and merge tools:

Approve a merge request:
```
"Approve MR #123"
```

Merge with options:

"Merge MR #456 with squash"
"Merge MR #789 and remove source branch"
"Merge MR #123 when pipeline succeeds"

Revoke approval (if needed):
```
"Unapprove MR #456"
```

Merge Options:

squash - Squash commits into a single commit
should_remove_source_branch - Delete source branch after merge
merge_when_pipeline_succeeds - Auto-merge when pipeline passes
sha - Ensure HEAD hasn't changed (safety check)

Note: You cannot approve your own MRs. The merge will fail if the MR has conflicts, is in draft status, or doesn't meet approval requirements.

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:

## Summary

**Total**: 45 | **Passed**: 42 | **Failed**: 3 | **Errors**: 0
**Pass Rate**: 93.3%

## Failed Tests

### [FAIL] test_login_with_invalid_password

**Duration**: 0.300s
**Class**: `tests.auth_test.TestAuth`

**Error Output**:
AssertionError: Expected 401, got 200

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:

View all commit discussions for a merge request:
```
"Show me commit discussions for MR #123"
```

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

MCP Config (Recommended)

Configure environment variables directly in your MCP client config as shown in Quick Setup. This keeps project-specific settings with the project.

Environment Variables

Alternatively, set environment variables in your shell:

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

SOCKS Proxy Support

Route all GitLab API requests through a SOCKS5 proxy by setting SOCKS_PROXY:

{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "gitlab-mcp",
      "env": {
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_PROJECT_ID": "12345",
        "SOCKS_PROXY": "socks5://127.0.0.1:1080"
      }
    }
  }
}

Or via environment variable:

export SOCKS_PROXY=socks5://127.0.0.1:1080

When SOCKS_PROXY is not set, connections are made directly (no proxy).

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

Project Discovery Tools

Tool	Description	Parameters
`search_projects`	Primary - Fast search by name (use this first)	`search`, `membership`, `limit`
`list_my_projects`	List all projects (slower, use for browsing)	`owned`, `limit`

Merge Request Tools

All project-scoped tools accept an optional project_id parameter. If not provided, falls back to GITLAB_PROJECT_ID env var.

Tool	Description	Parameters
`list_merge_requests`	List merge requests	`project_id`, `state`, `target_branch`, `limit`
`get_merge_request_details`	Get MR details	`project_id`, `merge_request_iid`
`create_merge_request`	Create a new merge request	`project_id`, `source_branch`, `target_branch`, `title`...
`update_merge_request`	Update an existing merge request	`project_id`, `merge_request_iid`, `title`, `assignees`...
`merge_merge_request`	Merge an MR	`project_id`, `merge_request_iid`, `squash`, `sha`...
`approve_merge_request`	Approve an MR	`project_id`, `merge_request_iid`, `sha`
`unapprove_merge_request`	Revoke approval from an MR	`project_id`, `merge_request_iid`
`get_pipeline_test_summary`	Get test summary (fast overview)	`project_id`, `merge_request_iid`
`get_merge_request_test_report`	Get detailed test failure reports	`project_id`, `merge_request_iid`
`get_merge_request_pipeline`	Get pipeline with all jobs	`project_id`, `merge_request_iid`
`get_job_log`	Get trace/output for specific job	`project_id`, `job_id`
`get_merge_request_reviews`	Get reviews/discussions	`project_id`, `merge_request_iid`
`get_commit_discussions`	Get discussions on commits	`project_id`, `merge_request_iid`
`get_branch_merge_requests`	Find MRs for branch	`project_id`, `branch_name`
`reply_to_review_comment`	Reply to existing discussion	`project_id`, `merge_request_iid`, `discussion_id`, `body`
`create_review_comment`	Create new discussion thread	`project_id`, `merge_request_iid`, `body`
`resolve_review_discussion`	Resolve/unresolve discussion	`project_id`, `merge_request_iid`, `discussion_id`
`list_project_members`	List project members	`project_id`
`list_project_labels`	List project labels	`project_id`

Roadmap

Recently Added

v1.4.0: Project discovery tools, MCP best practices (tool titles, annotations), improved prompts
v1.3.1: Fixed multi-workspace environment variable conflict in Cursor
v1.3.0: SOCKS5 proxy support for routing GitLab API requests
v1.2.0: Merge, approve, and unapprove MR tools - complete MR lifecycle
v1.1.0: Create and update MR tools, cleaner output formatting

Coming Next

Issue Management - List, create, update issues and add comments
Inline Comments - Add code review comments on specific lines

Considering

Lightweight file list for MRs (changed files without full diff)
Rebase MR via API

Out of Scope

Branch operations, file content fetching, and full diffs are intentionally not included - use git locally for these tasks, it's faster and more capable.

Have a feature request? Open an issue!

Development

Project Structure

gitlab_mr_mcp/
├── __init__.py          # Package version
├── __main__.py          # Entry point for python -m
├── server.py            # MCP server implementation
├── config.py            # Configuration management
├── gitlab_api.py        # GitLab API client
├── utils.py             # Utility functions
├── logging_config.py    # Logging configuration
└── tools/               # Tool implementations
    ├── __init__.py
    ├── list_merge_requests.py
    ├── get_merge_request_details.py
    ├── create_merge_request.py
    ├── update_merge_request.py
    └── ... (more tools)

Adding Tools

Create new file in gitlab_mr_mcp/tools/ directory
Add import and export to gitlab_mr_mcp/tools/__init__.py
Add to list_tools() in gitlab_mr_mcp/server.py
Add handler to call_tool() in gitlab_mr_mcp/server.py

Adding Prompts

Prompts provide workflow guidance to AI assistants. Add new prompts in gitlab_mr_mcp/prompts.py:

Define the prompt content as a string constant
Add entry to the PROMPTS dictionary with title, description, and content

NEW_PROMPT = """
Your prompt content here - focus on decision trees and when to use which tool.
"""

PROMPTS = {
    # ... existing prompts ...
    "new-prompt": {
        "title": "Human Readable Title",
        "description": "Short description for prompt list",
        "content": NEW_PROMPT,
    },
}

Development Setup

Install development dependencies:

make install
# or: uv pip install -e ".[dev]"

Available make commands:

make install   # Install in editable mode with dev deps
make dev       # Build and install wheel locally
make test      # Run tests
make lint      # Run linters
make format    # Format code
make check     # Lint + test
make clean     # Remove build artifacts

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

Format all existing code (first time only):

make format
# or: black --line-length=120 . && isort --profile black --line-length=120 .

Run pre-commit manually on all files:

pre-commit run --all-files

Running Tests

make test
# or: uv run pytest tests/ -v

Security Notes

Never commit access tokens to version control
Use project-specific tokens with minimal permissions (read_api scope)
Rotate tokens regularly
Store tokens in your MCP config (which should not be committed)

Support

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

License

MIT License - see LICENSE file for details.

GitLab MCP Server

GitLab MR MCP

Table of Contents

Quick Setup

Installation

Get your GitLab token

Configure your MCP client

Multi-Project Setup (Recommended)

Single-Project Setup

What You Can Do

Multi-Project Workflow

Single-Project Commands

Working with Review Comments

Approving and Merging

Working with Test Reports (Recommended for Test Failures)

Option 1: Test Summary (Fast & Lightweight) ⚡

Option 2: Full Test Report (Detailed) 🔍

Working with Pipeline Jobs and Logs

Step 1: Get Pipeline Overview

Step 2: Get Specific Job Logs

Typical Workflow:

Working with Commit Discussions

Configuration Options

MCP Config (Recommended)

Environment Variables

SOCKS Proxy Support

Find Your Project ID

Troubleshooting

Tool Reference

Project Discovery Tools

Merge Request Tools

Roadmap

Recently Added

Coming Next

Considering

Out of Scope

Development

Project Structure

Adding Tools

Adding Prompts

Development Setup

Running Tests

Security Notes

Support

License

GitLab MR MCP

Table of Contents

Quick Setup

Installation

Get your GitLab token

Configure your MCP client

Multi-Project Setup (Recommended)

Single-Project Setup

What You Can Do

Multi-Project Workflow

Single-Project Commands

Working with Review Comments

Approving and Merging

Working with Test Reports (Recommended for Test Failures)

Option 1: Test Summary (Fast & Lightweight) ⚡

Option 2: Full Test Report (Detailed) 🔍

Working with Pipeline Jobs and Logs

Step 1: Get Pipeline Overview

Step 2: Get Specific Job Logs

Typical Workflow:

Working with Commit Discussions

Configuration Options

MCP Config (Recommended)

Environment Variables

SOCKS Proxy Support

Find Your Project ID

Troubleshooting

Tool Reference

Project Discovery Tools

Merge Request Tools

Roadmap

Recently Added

Coming Next

Considering

Out of Scope