Gitlab Review MCP

A Model Context Protocol (MCP) server for GitLab code review and project management. Provides comprehensive tools for interacting with GitLab projects, merge requests, issues, and code reviews through Claude AI.

Features

• GitLab Integration - Complete GitLab API integration using python-gitlab
• Code Review Tools - List projects, MRs, view diffs, and add comments
• Merge Request Management - Create, update, and review merge requests
• Suggestion Support - View and apply code change suggestions
• Issue Tracking - Fetch and manage GitLab issues
• Line Comments - Add precise code review comments to specific lines
• Comment Management - Update existing comments and reply to discussions
• Singleton Pattern - Efficient connection reuse across all tools
• Type Safety - Full Pydantic validation with structured models
• Error Handling - Comprehensive error reporting and graceful failure modes
• Logging - Centralized logging configuration with optional console output

Installation

Using uvx (Recommended)

uvx gitlab-review-mcp

Using uv

uv add gitlab-review-mcp
uv run gitlab-review-mcp

Configuration

Environment Variables

Required:

• GITLAB_URL - GitLab instance URL (default: https://gitlab.com)
• GITLAB_PRIVATE_TOKEN - Your GitLab personal access token

Optional:

• GITLAB_REVIEW_MCP_SHOW_LOGS - Set to "true" to enable detailed logging (default: false)

Getting Your GitLab Token

1. Go to your GitLab instance (e.g., https://gitlab.com)
2. Navigate to Settings → Access Tokens
3. Create a new token with the following scopes:
   • api - Full API access
   • read_api - Read API (if you only need read operations)
4. Copy the token and add it to your environment configuration

Transport Types

1. stdio (default) - Standard input/output, client launches server automatically
2. http (recommended for remote) - Modern HTTP transport (aliases: streamable-http, streamable_http)
3. sse (legacy) - Server-Sent Events transport (deprecated)

🚀 Quick Start (uvx)

Stdio Transport

{
  "mcpServers": {
    "gitlab-review-mcp": {
      "command": "uvx",
      "args": ["--no-progress", "gitlab-review-mcp"],
      "env": {
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_PRIVATE_TOKEN": "your-token-here",
        "GITLAB_REVIEW_MCP_SHOW_LOGS": "false"
      }
    }
  }
}

HTTP Transport

Start server:

uvx --no-progress gitlab-review-mcp --transport http --port 8000 --host 0.0.0.0

Client config:

{
  "mcpServers": {
    "gitlab-review-mcp": {
      "url": "http://localhost:8000/mcp",
      "transport": "http"
    }
  }
}

SSE Transport

Start server:

uvx --no-progress gitlab-review-mcp --transport sse --port 8000 --host 0.0.0.0

Client config:

{
  "mcpServers": {
    "gitlab-review-mcp": {
      "url": "http://localhost:8000/sse",
      "transport": "sse"
    }
  }
}

🔧 Alternative Commands

Stdio with uv run --with

{
  "mcpServers": {
    "gitlab-review-mcp": {
      "command": "uv",
      "args": ["run", "--with", "gitlab-review-mcp", "gitlab-review-mcp"],
      "env": {
"GITLAB_REVIEW_MCP_SHOW_LOGS": "false"
      }
    }
  }
}

Stdio with uv run --directory (Local Development)

{
  "mcpServers": {
    "gitlab-review-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/gitlab-review-mcp", "gitlab-review-mcp"],
      "env": {
"GITLAB_REVIEW_MCP_SHOW_LOGS": "true"
      }
    }
  }
}

HTTP/SSE Alternative Commands

All transport types can use these alternative commands:

# Using uv run --with
uv run --with gitlab-review-mcp gitlab-review-mcp --transport http --port 8000

# Using uv run --directory (local development)
cd /path/to/gitlab-review-mcp
uv run gitlab-review-mcp --transport http --port 8000

Available Tools

Project Management

search_projects

Search for GitLab projects by keyword with pagination support.

Search Capabilities:

• Performs substring matching across project name, path, namespace, and description

• Note: Does not support regex or exact matching - simple keyword search only

• Parameters:

  • search (required) - Search keyword for substring matching
  • owned (optional) - Only show owned projects (default: false)
  • membership (optional) - Only show projects you're a member of (default: true)
  • page (optional) - Page number for pagination (default: 1)
  • per_page (optional) - Results per page (default: 20, max: 100)
  • order_by (optional) - Sort by: id, name, created_at, star_count, last_activity_at (default)
  • sort (optional) - Sort order: asc or desc (default)

• Returns: Formatted list of projects with ID, name, description, URL, default branch, and pagination info

Merge Request Operations

list_merge_requests

List merge requests for a specific project with pagination support.

• Parameters:
  • project_id (required) - GitLab project ID
  • state (optional) - Filter by state: opened, closed, merged, all
  • author_id (optional) - Filter by author user ID
  • assignee_id (optional) - Filter by assignee user ID
  • labels (optional) - Filter by label names (comma-separated)
  • page (optional) - Page number for pagination (default: 1)
  • per_page (optional) - Results per page (default: 20, max: 100)
• Returns: Formatted list of MRs with IID, title, state, author, branches, URLs, and pagination info

get_merge_request

Fetch detailed merge request information.

• Parameters:
  • project_id (required) - GitLab project ID
  • mr_iid (required) - Merge request IID (e.g., !123)
• Returns: MR details including title, description, state, branches, author, and timestamps

get_merge_request_diffs

Get code changes (diffs) for a merge request with pagination support.

• Parameters:
  • project_id (required) - GitLab project ID
  • mr_iid (required) - Merge request IID
  • page (optional) - Page number for pagination (default: 1)
  • per_page (optional) - Results per page (default: 20, max: 100)
• Returns: Complete diff information including file paths, commit SHAs, code changes, and pagination info

add_merge_request_comment

Add a general comment to a merge request.

• Parameters:
  • project_id (required) - GitLab project ID
  • mr_iid (required) - Merge request IID
  • comment (required) - Comment text
• Returns: Confirmation with comment ID and details

add_merge_request_line_comment

Add a line-specific comment to merge request code.

• Parameters:
  • project_id (required) - GitLab project ID
  • mr_iid (required) - Merge request IID
  • file_path (required) - File path in repository
  • line_number (required) - Line number in new version
  • comment (required) - Comment text
  • base_sha (required) - Base commit SHA (from diff)
  • head_sha (required) - Head commit SHA (from diff)
  • start_sha (required) - Start commit SHA (from diff)
  • old_line (optional) - Line number in old version
• Returns: Confirmation with discussion ID and comment details

get_merge_request_comments

Get all comments and discussions from a merge request, including suggestions, with pagination support.

• Parameters:
  • project_id (required) - GitLab project ID
  • mr_iid (required) - Merge request IID
  • page (optional) - Page number for pagination (default: 1)
  • per_page (optional) - Results per page (default: 20, max: 100)
• Returns: All comments with note IDs, discussion IDs, authors, timestamps, embedded suggestions, and pagination info

get_merge_request_commits

Get all commits in a merge request with pagination support.

• Parameters:
  • project_id (required) - GitLab project ID
  • mr_iid (required) - Merge request IID
  • page (optional) - Page number for pagination (default: 1)
  • per_page (optional) - Results per page (default: 20, max: 100)
• Returns: List of commits with SHA, title, message, author, timestamps, and pagination info

update_merge_request_comment

Update an existing merge request comment.

• Parameters:
  • project_id (required) - GitLab project ID
  • mr_iid (required) - Merge request IID
  • note_id (required) - Note ID to update
  • comment (required) - Updated comment text
• Returns: Confirmation with updated comment details

reply_to_merge_request_comment

Reply to an existing discussion thread.

• Parameters:
  • project_id (required) - GitLab project ID
  • mr_iid (required) - Merge request IID
  • discussion_id (required) - Discussion ID to reply to
  • comment (required) - Reply comment text
• Returns: Confirmation with reply details

update_merge_request

Update merge request title and/or description.

• Parameters:
  • project_id (required) - GitLab project ID
  • mr_iid (required) - Merge request IID
  • title (optional) - New title
  • description (optional) - New description
• Returns: Updated MR details

Suggestion Management

apply_suggestion

Apply a single code change suggestion.

• Parameters:
  • suggestion_id (required) - Suggestion ID to apply
• Returns: Confirmation with commit ID

apply_suggestions

Apply multiple code change suggestions in batch.

• Parameters:
  • suggestion_ids (required) - List of suggestion IDs to apply
• Returns: Confirmation with commit ID and applied suggestion IDs

Issue Management

get_issue

Fetch detailed issue information.

• Parameters:
  • project_id (required) - GitLab project ID
  • issue_iid (required) - Issue IID (e.g., #123)
• Returns: Issue details including title, description, state, assignees, labels, and timestamps

Testing

The project includes comprehensive tests:

# Run all tests
make test

# Run with coverage
make test-cov

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/midodimori/gitlab-review-mcp.git
cd gitlab-review-mcp

# Install with development dependencies
make install-dev

# Run tests
make test

# Format and lint code
make format

# Check code style and types
make lint

# Run the server locally
make run

# See all available commands
make help

Project Structure

gitlab-review-mcp/
├── src/gitlab_review_mcp/
│   ├── __init__.py
│   ├── server.py                  # MCP server implementation
│   ├── config.py                  # Configuration settings
│   ├── services/                  # Business logic layer
│   │   ├── __init__.py
│   │   └── gitlab_service.py      # GitLab API service
│   ├── tools/                     # MCP tool implementations
│   │   ├── __init__.py
│   │   └── gitlab_tools.py        # GitLab tools (14 tools)
│   └── utils/                     # Utility modules
│       ├── __init__.py
│       └── logging.py             # Logging configuration
├── tests/
│   ├── __init__.py
│   ├── test_server.py             # Tool function tests with mocks
│   ├── test_pagination.py         # Pagination-specific tests
│   └── test_mcp_integration.py    # MCP integration tests
├── LICENSE
├── Makefile
├── PUBLISHING.md                  # Publishing guide
├── pyproject.toml                 # Project configuration
├── pytest.ini
└── README.md

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• Model Context Protocol
• FastMCP Framework
• Claude Desktop

Support

For questions, issues, or contributions:

• Open an issue on GitHub
• Check the comprehensive test suite for usage examples