gitlab-mcp

GitLab MCP Server

A Model Context Protocol (MCP) server that provides tools to interact with GitLab merge requests. This server runs as a local tool using stdio transport, allowing MCP clients (like Claude Desktop) to retrieve comprehensive information about GitLab merge requests.

Features

• Get merge request basic information
• Retrieve all commits in a merge request
• Get file changes and diffs
• Access discussions and comments
• View approval status
• Check CI/CD pipeline status
• Get all information at once with a single command

Prerequisites

• Node.js 18 or higher
• GitLab account with API access
• GitLab personal access token with api or read_api scope

Installation

1. Clone or download this repository
2. Install dependencies:

npm install

1. Build the project:

npm run build

1. Create a .env file based on .env.example:

cp .env.example .env

1. Edit .env and add your GitLab credentials:

GITLAB_INSTANCE_URL=https://gitlab.com
GITLAB_API_TOKEN=your-personal-access-token
GITLAB_PROJECT_ID=your-project-id

Getting Your GitLab Configuration

GitLab Instance URL:

• For gitlab.com: https://gitlab.com
• For self-hosted: Your GitLab instance URL (e.g., https://gitlab.example.com)

API Token:

1. Go to GitLab → User Settings → Access Tokens
2. Create a personal access token with api or read_api scope
3. Copy the token (you won't be able to see it again!)

Project ID:

• Found on your project's main page under the project name
• Or in Settings → General

Configuration for Claude Desktop

Add the following to your Claude Desktop MCP settings file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
      "env": {
        "GITLAB_INSTANCE_URL": "https://gitlab.com",
        "GITLAB_API_TOKEN": "your-api-token",
        "GITLAB_PROJECT_ID": "12345678"
      }
    }
  }
}

Replace /absolute/path/to/gitlab-mcp with the actual path to this project.

Alternatively, if you want to use the .env file, you can omit the env section, but make sure the .env file is in the project root.

Available Tools

get_merge_request

Get basic information about a merge request.

Parameters:

• merge_request_iid (number): The IID (internal ID) of the merge request

Returns: Basic MR info including title, description, state, branches, author, assignees, reviewers, labels, and merge status.

get_merge_request_commits

Get all commits in a merge request.

Parameters:

• merge_request_iid (number): The IID of the merge request

Returns: Array of commits with messages, authors, timestamps, and SHAs.

get_merge_request_diffs

Get all file changes and diffs in a merge request.

Parameters:

• merge_request_iid (number): The IID of the merge request

Returns: Array of file changes with line-by-line diffs.

get_merge_request_discussions

Get all discussions and comments on a merge request.

Parameters:

• merge_request_iid (number): The IID of the merge request

Returns: Array of discussion threads with notes, including review comments and system notes.

get_merge_request_approvals

Get approval status and information for a merge request.

Parameters:

• merge_request_iid (number): The IID of the merge request

Returns: Approval state including required approvals, approvals left, and who approved.

get_merge_request_pipelines

Get CI/CD pipeline information for a merge request.

Parameters:

• merge_request_iid (number): The IID of the merge request

Returns: Array of pipelines with status, ref, SHA, and timestamps.

get_merge_request_full

Get complete information about a merge request (all data in one call).

Parameters:

• merge_request_iid (number): The IID of the merge request

Returns: Complete merge request data including MR info, commits, diffs, discussions, approvals, pipelines, and latest pipeline jobs.

Usage Example

Once configured in Claude Desktop, you can use natural language to interact with your GitLab merge requests:

"Show me the details of merge request 42"
"What commits are in MR 15?"
"Get the diffs for merge request 8"
"Show me all comments on MR 23"
"What's the approval status of merge request 10?"
"Get everything about merge request 5"

Development

Build

npm run build

Watch mode (auto-rebuild on changes)

npm run watch

Troubleshooting

Authentication Errors

• Verify your GITLAB_API_TOKEN is correct and has the necessary scopes
• Check that the token hasn't expired

Resource Not Found

• Verify the GITLAB_PROJECT_ID is correct
• Ensure the merge request IID exists in the project
• Check that you have access to the project

Permission Denied

• Verify your GitLab account has at least Reporter access to the project
• Check that your API token has the api or read_api scope

GitLab API Permissions

The API token needs one of the following scopes:

• api - Full API access (recommended)
• read_api - Read-only API access (minimum required)

Additionally, your GitLab account needs at least Reporter level access to the project to view merge request information.

License

ISC