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

1. Go to your GitLab instance → User Settings → Access Tokens
2. Create a token with api scope
3. 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

1. Go to your GitLab instance
2. Navigate to User Settings > Access Tokens
3. 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:

1. Separate Parameters: projectId and mergeRequestIid
2. 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:

1. Check Cursor MCP Support: Ensure your Cursor version supports MCP servers
2. Verify Configuration: Check that the configuration is in the correct settings file
3. Test Connection: Run gitlab-mr-mcp in terminal to verify it works
4. 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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run linting and tests
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

1. Check the GitHub Issues
2. Create a new issue with detailed information
3. 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