GitLab MCP server for AI agents

The GitLab MCP Server allows you to interact with your GitLab projects directly through AI assistants. Connect your assistant to GitLab and perform tasks like viewing merge requests, checking reviews, and responding to discussions—all through natural language commands.

Installation

Prerequisites

Python 3.6+
Git
Access to a GitLab account with API permissions

Setup Steps

Clone and install the server:

git clone https://github.com/amirsina-mandegari/gitlab-mcp-server.git
cd gitlab-mcp-server
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
chmod +x run-mcp.sh

Create a GitLab access token:
- Navigate to GitLab → Settings → Access Tokens
- Generate a new token with the read_api scope
- Copy the token for configuration

Configure your project: Create a gitlab-mcp.env file in your project directory with:

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

Connect to your AI assistant: Create a .cursor/mcp.json file in your project:

{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "/path/to/gitlab-mcp-server/run-mcp.sh",
      "cwd": "/path/to/your-project"
    }
  }
}

Restart your AI assistant to establish the connection

Usage Guide

Basic Commands

Once connected, you can use natural language to interact with GitLab:

Query merge requests: List open merge requests
Get MR details: Show me details for merge request 456
View reviews: Get reviews and discussions for MR #123
Find branch MRs: Find merge requests for the feature/auth-improvements branch
Filter by status: Show me closed merge requests targeting main

Working with Reviews

The server allows full interaction with merge request discussions:

View reviews and discussions:

Use this to get discussion IDs which you'll need for replies:

Show me reviews for MR #123
Reply to discussions:

Once you have the discussion ID, you can reply:

Reply to discussion abc123 in MR #456 with 'I'll fix this in the next commit'
Create new comment threads:

Start a new discussion with:

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

Mark discussions as resolved:

Resolve discussion def456 in MR #123

Working with Commit Discussions

Get insights into discussions happening at the commit level:

View all commit discussions:

Show me commit discussions for MR #123
See complete commit conversation history:

Get all comments on commits in merge request #456

This is particularly useful for tracking review progress, understanding discussion history, and viewing comments in the context of specific code changes.

Configuration Options

Project-Specific Configuration (Recommended)

Create a gitlab-mcp.env file in each project for project-specific settings.

Global Configuration

For system-wide settings, use environment variables:

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

Finding Your Project ID

Check your GitLab project under Settings → General → Project ID
Alternatively, use the numeric ID in the project URL

Troubleshooting

Authentication Error: Verify your token has read_api permissions and hasn't expired
Project Not Found: Ensure the project ID is correct (numeric ID, not project name)
Connection Issues: Check that your GitLab URL is accessible and correctly formatted
Script Not Found: Confirm the path in your MCP config points to the actual server location

Tool Reference

Tool	Description	Parameters
`list_merge_requests`	List merge requests	`state`, `target_branch`, `limit`
`get_merge_request_details`	Get MR details	`merge_request_iid`
`get_merge_request_reviews`	Get reviews/discussions	`merge_request_iid`
`get_commit_discussions`	Get discussions on commits	`merge_request_iid`
`get_branch_merge_requests`	Find MRs for branch	`branch_name`
`reply_to_review_comment`	Reply to existing discussion	`merge_request_iid`, `discussion_id`, `body`
`create_review_comment`	Create new discussion thread	`merge_request_iid`, `body`
`resolve_review_discussion`	Resolve/unresolve discussion	`merge_request_iid`, `discussion_id`, `resolved`

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "gitlab-mcp" '{"command":"/path/to/gitlab-mcp-server/run-mcp.sh","cwd":"/path/to/your-project"}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "gitlab-mcp": {
            "command": "/path/to/gitlab-mcp-server/run-mcp.sh",
            "cwd": "/path/to/your-project"
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "gitlab-mcp": {
            "command": "/path/to/gitlab-mcp-server/run-mcp.sh",
            "cwd": "/path/to/your-project"
        }
    }
}

3. Restart Claude Desktop for the changes to take effect