GitLab Code Review MCP Server

A Model Context Protocol (MCP) server that provides GitLab code review functionality for AI assistants. This server enables AI assistants to interact with GitLab merge requests, review code changes, and create draft comments.

Features

• Project Discovery: Search and list GitLab projects

• Merge Request Management: List and filter merge requests

• Code Diff Analysis: Retrieve detailed code changes for merge requests

• Draft Comment Creation: Create both general and line-specific draft comments

Quick Start

Prerequisites

• Node.js (ES2022+ support required)

• pnpm package manager (version 10.11.1+ recommended)

• GitLab Personal Access Token with API access

Installation

1. Clone the repository:

   git clone <repository-url> cd code-review-mcp

2. Install dependencies:

   pnpm install

3. Configure environment:

   cp .env.example .env

   Edit .env with your GitLab configuration:

   GITLAB_PAT=your_gitlab_personal_access_token_here GITLAB_API_URL=https://gitlab.com GITLAB_PROJECT_ID=your_project_id_here SERVER_NAME=code-review-mcp SERVER_VERSION=1.0.0

4. Build the project:

   pnpm run build

5. Run the server:

   node build/index.js

MCP Tools

The server exposes four main tools for GitLab integration:

get-projects

Search and list GitLab projects.

Parameters:

• search (optional): Search term to filter projects

• per_page (optional): Number of results per page (default: 20, max: 100)

• visibility (optional): Filter by visibility ('private', 'internal', 'public')

• owned (optional): Limit to owned projects (boolean)

get-merge-requests

List merge requests from a project.

Parameters:

• state (optional): Filter by state ('opened', 'closed', 'merged', 'all') - default: 'opened'

• per_page (optional): Number of results per page (default: 20, max: 100)

get-merge-request-diffs

Get detailed code changes for a specific merge request.

Parameters:

• mr_iid (optional): Internal ID of the merge request

• source_branch (optional): Source branch name to search for

• mrTitle (optional): Title or partial title to search for

create-draft-note

Create draft comments on merge requests.

Parameters:

• project_id (optional): Project ID (uses default if not provided)

• mr_iid (required): Internal ID of the merge request

• note (required): Content of the draft note

• position_type (optional): Set to 'text' for line-specific comments

• old_path, new_path (optional): File paths for line comments

• old_line, new_line (optional): Line numbers for line comments

• base_sha, start_sha, head_sha (optional): SHA values for line comments

Configuration

Environment Variables

All environment variables are validated at startup using Zod schemas:

• GITLAB_PAT (required): GitLab Personal Access Token with API access

• GITLAB_API_URL (required): GitLab instance URL (e.g., https://gitlab.com)

• GITLAB_PROJECT_ID (required): Default project ID (numeric)

• SERVER_NAME (required): MCP server name identifier

• SERVER_VERSION (required): Server version string

GitLab Personal Access Token

Your GitLab PAT needs the following scopes:

• api - Full API access

• read_user - Read user information

• read_repository - Read repository content

Development

Project Structure

Building

This compiles TypeScript from src/ to build/ directory and makes the output executable.

Testing

Run the comprehensive test suite:

This test verifies:

• Build process functionality

• Output file generation and permissions

• Environment variable validation

• MCP server initialization

Code Architecture

Entry Point: src/index.ts

• Creates MCP server instance

• Registers four GitLab tools

• Handles stdio transport communication

Environment Management: src/env.ts

• Uses Zod for runtime environment validation

• Exports typed environment configuration

• Fails fast on invalid configuration

Key Components:

• makeGitLabRequest<T>() - Generic GitLab API client function

• Interface definitions for GitLab entities (MergeRequest, Diff, Project, DraftNote)

• MCP tool handlers with Zod schema validation

Usage with AI Assistants

This MCP server is designed to be used with AI assistants that support the Model Context Protocol. See docs/system-prompt.md for detailed instructions on how AI assistants can use this server for code review workflows.

Example Workflow

1. Discover Projects: Use get-projects to find target repositories

2. List Merge Requests: Use get-merge-requests to see open merge requests

3. Analyze Code: Use get-merge-request-diffs to review code changes

4. Provide Feedback: Use create-draft-note to create constructive comments

MCP Client Configuration

To use this MCP server with AI assistants like Claude Code, you need to add the server configuration to your MCP client settings. Here's how to configure it:

For Claude Code

Add the following configuration to your MCP client settings (typically in a JSON configuration file):

Configuration Steps

1. Build the project first (if not already done):

   pnpm run build

2. Replace the placeholder values:

   • <ABSOLUTE_PATH_TO_code-review-mcp/build/index.js>: Replace with the full absolute path to your built server file

   • GITLAB_PROJECT_ID: Your GitLab project ID (numeric)

   • GITLAB_PAT: Your GitLab Personal Access Token

   • GITLAB_API_URL: Your GitLab instance URL (e.g., https://gitlab.com)

   • SERVER_NAME: A name for your server instance (e.g., code-review-mcp)

   • SERVER_VERSION: Version identifier (e.g., 1.0.0)

3. Example with actual values:

   { "mcpServers": { "code-review": { "command": "node", "args": [ "/Users/yourname/projects/code-review-mcp/build/index.js" ], "env": { "GITLAB_PROJECT_ID": "12345678", "GITLAB_PAT": "glpat-xxxxxxxxxxxxxxxxxxxx", "GITLAB_API_URL": "https://gitlab.com", "SERVER_NAME": "code-review-mcp", "SERVER_VERSION": "1.0.0" } } } }

4. Restart your MCP client after adding the configuration.

Security Notes

• Keep your GitLab Personal Access Token secure and never commit it to version control

• Use environment-specific configuration files that are excluded from your repository

• Ensure your GitLab PAT has only the minimum required permissions (api, read_user, read_repository)

API Integration

The server integrates with GitLab's REST API v4:

• Authentication: Uses PRIVATE-TOKEN header with GitLab PAT

• Base URL Pattern: ${GITLAB_API_URL}/api/v4/...

• Error Handling: All API calls include comprehensive error handling

• Rate Limiting: Respects GitLab API rate limits

Security Considerations

• Token Security: Store GitLab PAT securely and use minimal required permissions

• Input Validation: All user inputs are validated through Zod schemas

• Error Messages: Sensitive information is not exposed in error responses

• Environment Variables: Never commit actual credentials to version control

License

ISC

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

Support

For issues and questions:

1. Check the existing documentation in docs/

2. Review the test files for usage examples

3. Open an issue with detailed information about your problem