GitLab MCP Server

A Model Context Protocol (MCP) server for GitLab that provides comprehensive merge request management capabilities. This server allows you to interact with your self-hosted GitLab installation to get open merge requests, view MR details, reply to comments, mark comments as resolved, and much more.

Requirements

Node.js: Version 16.0.0 or higher
GitLab: Self-hosted GitLab instance with API access
GitLab Access Token: Personal access token with api scope

Note: For detailed Node.js compatibility information, see COMPATIBILITY.md

Quick Start

1. Install the Package

npm install -g @erp-ai/gitlab-mr-mcp

2. Set Up GitLab Token

Go to your GitLab instance → User Settings → Access Tokens
Create a token with api scope
Set environment variables:

export GITLAB_BASE_URL="https://your-gitlab-instance.com"
export GITLAB_TOKEN="your-personal-access-token"

3. Configure Your MCP Client

For Claude Desktop: Add to claude_desktop_config.json:

{
  "mcpServers": {
    "gitlab-mr": {
      "command": "npx",
      "args": ["@erp-ai/gitlab-mr-mcp"],
      "env": {
        "GITLAB_BASE_URL": "https://your-gitlab-instance.com",
        "GITLAB_TOKEN": "your-access-token"
      }
    }
  }
}

For Cursor IDE: Add to Cursor settings:

{
  "mcp.servers": {
    "gitlab-mr": {
      "command": "gitlab-mr-mcp",
      "args": [],
      "env": {
        "GITLAB_BASE_URL": "https://your-gitlab-instance.com",
        "GITLAB_TOKEN": "your-access-token"
      }
    }
  }
}

4. Start Using

Now you can use natural language commands:

"Get open merge requests for my project"
"Show discussions for https://gitlab.example.com/group/project/-/merge_requests/123"
"Create a comment saying 'LGTM!' on that MR"
"Approve the merge request"

Features

Complete GitLab API Integration: Full support for merge request operations
Comment Management: Create, update, delete, and reply to comments
Discussion Management: Resolve/unresolve discussions and reply to threads
MR Operations: Approve, unapprove, and merge requests
Project Management: List and access project information
Flexible Input: Accept either project ID + MR IID or direct GitLab MR URLs
Comprehensive Error Handling: Detailed error messages for troubleshooting
TypeScript Support: Full type definitions included
Extensive Testing: Comprehensive unit test coverage

Installation

As a Global Package

npm install -g @erp-ai/gitlab-mr-mcp

As a Project Dependency

npm install @erp-ai/gitlab-mr-mcp

Testing Compatibility

To verify that the package works with your Node.js version:

npm run test:compatibility

Configuration

Environment Variables

Create a .env file in your project root or set these environment variables:

GITLAB_BASE_URL=https://your-gitlab-instance.com
GITLAB_TOKEN=your-gitlab-access-token
GITLAB_PROJECT_ID=your-default-project-id  # Optional

GitLab Access Token

Go to your GitLab instance
Navigate to User Settings > Access Tokens
Create a new token with the following scopes:
- api - Full API access
- read_user - Read user information
- read_repository - Read repository information

Usage

As a Standalone MCP Server

# If installed globally
@erp-ai/gitlab-mr-mcp

# If installed locally
npx @erp-ai/gitlab-mr-mcp

As a Library

import { GitLabMCPServer, GitLabClient } from '@erp-ai/gitlab-mr-mcp';

// Use the MCP Server
const server = new GitLabMCPServer();
server.run();

// Or use the GitLab client directly
const client = new GitLabClient({
  baseUrl: 'https://your-gitlab-instance.com',
  token: 'your-access-token'
});

// Get open merge requests
const openMRs = await client.getOpenMergeRequests('project-id');
console.log(openMRs);

MCP Tools

The server provides the following tools. All merge request tools support both separate parameters and GitLab MR URLs:

Input Formats

For merge request operations, you can use either:

Separate Parameters: projectId and mergeRequestIid
GitLab MR URL: mergeRequestUrl (e.g., https://gitlab.example.com/group/project/-/merge_requests/123)

Project Management

`get_projects`

Get all GitLab projects accessible to the authenticated user.

{
  "name": "get_projects"
}

`get_project`

Get details of a specific GitLab project.

{
  "name": "get_project",
  "arguments": {
    "projectId": "123"
  }
}

Merge Request Operations

`get_open_merge_requests`

Get all open merge requests for a project.

{
  "name": "get_open_merge_requests",
  "arguments": {
    "projectId": "123"
  }
}

`get_all_merge_requests`

Get all merge requests for a project with optional state filtering.

{
  "name": "get_all_merge_requests",
  "arguments": {
    "projectId": "123",
    "state": "opened"
  }
}

`get_merge_request`

Get detailed information about a specific merge request.

Using separate parameters:

{
  "name": "get_merge_request",
  "arguments": {
    "projectId": "123",
    "mergeRequestIid": 1
  }
}

Using GitLab MR URL:

{
  "name": "get_merge_request",
  "arguments": {
    "mergeRequestUrl": "https://gitlab.example.com/group/project/-/merge_requests/1"
  }
}

`get_merge_request_changes`

Get the diff/changes for a merge request.

Using separate parameters:

{
  "name": "get_merge_request_changes",
  "arguments": {
    "projectId": "123",
    "mergeRequestIid": 1
  }
}

Using GitLab MR URL:

{
  "name": "get_merge_request_changes",
  "arguments": {
    "mergeRequestUrl": "https://gitlab.example.com/group/project/-/merge_requests/1"
  }
}

Comment and Discussion Management

`get_merge_request_notes`

Get all notes (comments) for a merge request.

Using separate parameters:

{
  "name": "get_merge_request_notes",
  "arguments": {
    "projectId": "123",
    "mergeRequestIid": 1
  }
}

Using GitLab MR URL:

{
  "name": "get_merge_request_notes",
  "arguments": {
    "mergeRequestUrl": "https://gitlab.example.com/group/project/-/merge_requests/1"
  }
}

`get_comments_from_url`

Get all comments from a GitLab merge request URL (convenient method).

{
  "name": "get_comments_from_url",
  "arguments": {
    "mergeRequestUrl": "https://code.deskera.com/infinity-stones/erp-ai/-/merge_requests/1979"
  }
}

`get_merge_request_discussions`

Get all discussions for a merge request.

Using separate parameters:

{
  "name": "get_merge_request_discussions",
  "arguments": {
    "projectId": "123",
    "mergeRequestIid": 1
  }
}

Using GitLab MR URL:

{
  "name": "get_merge_request_discussions",
  "arguments": {
    "mergeRequestUrl": "https://gitlab.example.com/group/project/-/merge_requests/1"
  }
}

`create_merge_request_note`

Create a new note (comment) on a merge request.

Using separate parameters:

{
  "name": "create_merge_request_note",
  "arguments": {
    "projectId": "123",
    "mergeRequestIid": 1,
    "body": "This looks great! 👍"
  }
}

Using GitLab MR URL:

{
  "name": "create_merge_request_note",
  "arguments": {
    "mergeRequestUrl": "https://gitlab.example.com/group/project/-/merge_requests/1",
    "body": "This looks great! 👍"
  }
}

`reply_to_discussion`

Reply to a specific discussion thread.

Using separate parameters:

{
  "name": "reply_to_discussion",
  "arguments": {
    "projectId": "123",
    "mergeRequestIid": 1,
    "discussionId": "discussion-id",
    "body": "Thanks for the feedback!"
  }
}

Using GitLab MR URL:

{
  "name": "reply_to_discussion",
  "arguments": {
    "mergeRequestUrl": "https://gitlab.example.com/group/project/-/merge_requests/1",
    "discussionId": "discussion-id",
    "body": "Thanks for the feedback!"
  }
}

`resolve_discussion`

Resolve or unresolve a discussion.

Using separate parameters:

{
  "name": "resolve_discussion",
  "arguments": {
    "projectId": "123",
    "mergeRequestIid": 1,
    "discussionId": "discussion-id",
    "resolved": true
  }
}

Using GitLab MR URL:

{
  "name": "resolve_discussion",
  "arguments": {
    "mergeRequestUrl": "https://gitlab.example.com/group/project/-/merge_requests/1",
    "discussionId": "discussion-id",
    "resolved": true
  }
}

`update_note`

Update an existing note/comment.

Using separate parameters:

{
  "name": "update_note",
  "arguments": {
    "projectId": "123",
    "mergeRequestIid": 1,
    "noteId": 456,
    "body": "Updated comment content"
  }
}

Using GitLab MR URL:

{
  "name": "update_note",
  "arguments": {
    "mergeRequestUrl": "https://gitlab.example.com/group/project/-/merge_requests/1",
    "noteId": 456,
    "body": "Updated comment content"
  }
}

`delete_note`

Delete a note/comment.

Using separate parameters:

{
  "name": "delete_note",
  "arguments": {
    "projectId": "123",
    "mergeRequestIid": 1,
    "noteId": 456
  }
}

Using GitLab MR URL:

{
  "name": "delete_note",
  "arguments": {
    "mergeRequestUrl": "https://gitlab.example.com/group/project/-/merge_requests/1",
    "noteId": 456
  }
}

Merge Request Actions

`approve_merge_request`

Approve a merge request.

Using separate parameters:

{
  "name": "approve_merge_request",
  "arguments": {
    "projectId": "123",
    "mergeRequestIid": 1
  }
}

Using GitLab MR URL:

{
  "name": "approve_merge_request",
  "arguments": {
    "mergeRequestUrl": "https://gitlab.example.com/group/project/-/merge_requests/1"
  }
}

`unapprove_merge_request`

Remove approval from a merge request.

Using separate parameters:

{
  "name": "unapprove_merge_request",
  "arguments": {
    "projectId": "123",
    "mergeRequestIid": 1
  }
}

Using GitLab MR URL:

{
  "name": "unapprove_merge_request",
  "arguments": {
    "mergeRequestUrl": "https://gitlab.example.com/group/project/-/merge_requests/1"
  }
}

`merge_merge_request`

Merge a merge request with optional parameters.

Using separate parameters:

{
  "name": "merge_merge_request",
  "arguments": {
    "projectId": "123",
    "mergeRequestIid": 1,
    "mergeCommitMessage": "Custom merge message",
    "shouldRemoveSourceBranch": true,
    "squash": true
  }
}

Using GitLab MR URL:

{
  "name": "merge_merge_request",
  "arguments": {
    "mergeRequestUrl": "https://gitlab.example.com/group/project/-/merge_requests/1",
    "mergeCommitMessage": "Custom merge message",
    "shouldRemoveSourceBranch": true,
    "squash": true
  }
}

Utility

`test_connection`

Test the connection to GitLab and get current user info.

{
  "name": "test_connection"
}

Configuration with MCP Clients

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "gitlab-mr": {
      "command": "npx",
      "args": ["@erp-ai/gitlab-mr-mcp"],
      "env": {
        "GITLAB_BASE_URL": "https://your-gitlab-instance.com",
        "GITLAB_TOKEN": "your-access-token"
      }
    }
  }
}

Cursor IDE

Cursor IDE supports MCP servers through its AI assistant. To use this GitLab MCP server with Cursor:

1. Install the Package

npm install -g @erp-ai/gitlab-mr-mcp

2. Configure Environment Variables

Create a .env file in your project root or set system environment variables:

export GITLAB_BASE_URL="https://your-gitlab-instance.com"
export GITLAB_TOKEN="your-personal-access-token"
export GITLAB_PROJECT_ID="your-default-project-id"  # Optional

3. Configure Cursor

Add to your Cursor settings (File → Preferences → Settings → Extensions → MCP):

{
  "mcp.servers": {
    "gitlab-mr": {
      "command": "gitlab-mr-mcp",
      "args": [],
      "env": {
        "GITLAB_BASE_URL": "https://your-gitlab-instance.com",
        "GITLAB_TOKEN": "your-access-token",
        "GITLAB_PROJECT_ID": "your-default-project-id"
      }
    }
  }
}

4. Alternative: Use with npx

If you prefer not to install globally:

{
  "mcp.servers": {
    "gitlab-mr": {
      "command": "npx",
      "args": ["@erp-ai/gitlab-mr-mcp"],
      "env": {
        "GITLAB_BASE_URL": "https://your-gitlab-instance.com",
        "GITLAB_TOKEN": "your-access-token"
      }
    }
  }
}

5. Usage in Cursor

Once configured, you can use the GitLab MCP server in Cursor's AI assistant:

"Get open merge requests for project 123"
"Show me the discussions for https://gitlab.example.com/group/project/-/merge_requests/456"
"Create a comment on MR https://gitlab.example.com/group/project/-/merge_requests/789 saying 'LGTM!'"
"Approve the merge request https://gitlab.example.com/group/project/-/merge_requests/123"

6. Troubleshooting Cursor Setup

If the MCP server doesn't work in Cursor:

Check Cursor MCP Support: Ensure your Cursor version supports MCP servers
Verify Configuration: Check that the configuration is in the correct settings file
Test Connection: Run gitlab-mr-mcp in terminal to verify it works
Check Logs: Look at Cursor's developer console for error messages

Other MCP Clients

The server communicates via stdio and follows the MCP protocol. Configure your client to run:

npx @erp-ai/gitlab-mr-mcp

API Reference

GitLabClient

The main client class for interacting with GitLab API.

import { GitLabClient } from '@erp-ai/gitlab-mr-mcp';

const client = new GitLabClient({
  baseUrl: 'https://your-gitlab-instance.com',
  token: 'your-access-token'
});

Methods

getProjects() - Get all accessible projects
getProject(projectId) - Get project details
getOpenMergeRequests(projectId) - Get open merge requests
getAllMergeRequests(projectId, state?) - Get all merge requests
getMergeRequest(projectId, mergeRequestIid) - Get MR details
getMergeRequestNotes(projectId, mergeRequestIid) - Get MR notes
getMergeRequestDiscussions(projectId, mergeRequestIid) - Get MR discussions
createMergeRequestNote(projectId, mergeRequestIid, noteData) - Create note
replyToDiscussion(projectId, mergeRequestIid, discussionId, body) - Reply to discussion
resolveDiscussion(projectId, mergeRequestIid, discussionId, resolved) - Resolve discussion
updateNote(projectId, mergeRequestIid, noteId, body) - Update note
deleteNote(projectId, mergeRequestIid, noteId) - Delete note
getMergeRequestChanges(projectId, mergeRequestIid) - Get MR changes
approveMergeRequest(projectId, mergeRequestIid) - Approve MR
unapproveMergeRequest(projectId, mergeRequestIid) - Unapprove MR
mergeMergeRequest(projectId, mergeRequestIid, options?) - Merge MR
testConnection() - Test connection

Error Handling

The server provides detailed error messages for common issues:

Authentication errors: Invalid or expired tokens
Permission errors: Insufficient permissions for operations
Not found errors: Project or merge request not found
Validation errors: Invalid parameters or data

Development

Building

npm run build

Running in Development

npm run dev

Testing

npm test

Linting

npm run lint

Contributing

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

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

Check the GitHub Issues
Create a new issue with detailed information
Include your GitLab version and configuration (without sensitive data)

Changelog

v1.1.0

NEW: GitLab MR URL support - now accepts direct GitLab MR URLs for all tools
NEW: Cursor IDE integration instructions and configuration
IMPROVED: Enhanced documentation with quick start guide
IMPROVED: Better error handling for URL parsing
IMPROVED: Comprehensive test coverage (35 tests)

v1.0.0

Initial release
Support for all major GitLab merge request operations
Complete comment and discussion management
Comprehensive error handling
TypeScript support

@erp-ai/gitlab-mr-mcp

GitLab MCP Server

Requirements

Quick Start

1. Install the Package

2. Set Up GitLab Token

3. Configure Your MCP Client

4. Start Using

Features

Installation

As a Global Package

As a Project Dependency

Testing Compatibility

Configuration

Environment Variables

GitLab Access Token

Usage

As a Standalone MCP Server

As a Library

MCP Tools

Input Formats

Project Management

get_projects

get_project

Merge Request Operations

get_open_merge_requests

get_all_merge_requests

get_merge_request

get_merge_request_changes

Comment and Discussion Management

get_merge_request_notes

get_comments_from_url

get_merge_request_discussions

create_merge_request_note

reply_to_discussion

resolve_discussion

update_note

delete_note

Merge Request Actions

approve_merge_request

unapprove_merge_request

merge_merge_request

Utility

test_connection

Configuration with MCP Clients

Claude Desktop

Cursor IDE

1. Install the Package

2. Configure Environment Variables

3. Configure Cursor

4. Alternative: Use with npx

5. Usage in Cursor

6. Troubleshooting Cursor Setup

Other MCP Clients

API Reference

GitLabClient

Methods

Error Handling

Development

Building

Running in Development

Testing

Linting

Contributing

License

Support

Changelog

v1.1.0

v1.0.0

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

`get_projects`

`get_project`

`get_open_merge_requests`

`get_all_merge_requests`

`get_merge_request`

`get_merge_request_changes`

`get_merge_request_notes`

`get_comments_from_url`

`get_merge_request_discussions`

`create_merge_request_note`

`reply_to_discussion`

`resolve_discussion`

`update_note`

`delete_note`

`approve_merge_request`

`unapprove_merge_request`

`merge_merge_request`

`test_connection`

Weekly Downloads