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

Clone the repository:

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

Install dependencies:
```
pnpm install
```

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

Build the project:
```
pnpm run build
```
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

├── src/
│   ├── index.ts          # Main MCP server implementation
│   └── env.ts            # Environment configuration and validation
├── build/                # Compiled output (generated)
├── docs/
│   └── system-prompt.md  # AI assistant usage documentation
├── test_mcp_server.js    # Comprehensive test suite
├── test_draft_note.js    # Example requests for draft note tool
├── test_projects.js      # Example data for projects tool
├── .env.example          # Environment variable template
├── package.json          # Project configuration
└── tsconfig.json         # TypeScript configuration

Building

pnpm run build

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

Testing

Run the comprehensive test suite:

node test_mcp_server.js

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

Discover Projects: Use get-projects to find target repositories
List Merge Requests: Use get-merge-requests to see open merge requests
Analyze Code: Use get-merge-request-diffs to review code changes
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):

{
  "mcpServers": {
    "code-review": {
      "command": "node",
      "args": [
        "<ABSOLUTE_PATH_TO_code-review-mcp/build/index.js>"
      ],
      "env": {
        "GITLAB_PROJECT_ID": "",
        "GITLAB_PAT": "",
        "GITLAB_API_URL": "",
        "SERVER_NAME": "",
        "SERVER_VERSION": ""
      }
    }
  }
}

Configuration Steps

Build the project first (if not already done):
```
pnpm run build
```
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)

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"
      }
    }
  }
}

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

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Support

For issues and questions:

Check the existing documentation in docs/
Review the test files for usage examples
Open an issue with detailed information about your problem

GitLab Code Review MCP Server

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

Clone the repository:

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

Install dependencies:
```
pnpm install
```

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

Build the project:
```
pnpm run build
```
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

├── src/
│   ├── index.ts          # Main MCP server implementation
│   └── env.ts            # Environment configuration and validation
├── build/                # Compiled output (generated)
├── docs/
│   └── system-prompt.md  # AI assistant usage documentation
├── test_mcp_server.js    # Comprehensive test suite
├── test_draft_note.js    # Example requests for draft note tool
├── test_projects.js      # Example data for projects tool
├── .env.example          # Environment variable template
├── package.json          # Project configuration
└── tsconfig.json         # TypeScript configuration

Building

pnpm run build

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

Testing

Run the comprehensive test suite:

node test_mcp_server.js

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

Example Workflow

Discover Projects: Use get-projects to find target repositories
List Merge Requests: Use get-merge-requests to see open merge requests
Analyze Code: Use get-merge-request-diffs to review code changes
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):

{
  "mcpServers": {
    "code-review": {
      "command": "node",
      "args": [
        "<ABSOLUTE_PATH_TO_code-review-mcp/build/index.js>"
      ],
      "env": {
        "GITLAB_PROJECT_ID": "",
        "GITLAB_PAT": "",
        "GITLAB_API_URL": "",
        "SERVER_NAME": "",
        "SERVER_VERSION": ""
      }
    }
  }
}

Configuration Steps

Build the project first (if not already done):
```
pnpm run build
```
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)

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"
      }
    }
  }
}

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

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Support

For issues and questions:

Check the existing documentation in docs/
Review the test files for usage examples
Open an issue with detailed information about your problem