GitLab MCP Server

[!NOTE] This documentation is available in 简体中文.

A GitLab API server built on the Model Context Protocol (MCP). This server provides a set of tools that allow AI models to interact with GitLab instances, with a focus on branch management and merge request (MR) operations.

Project Info

• Package: @jesbrian/gitlab-mcp-server
• Version: 0.2.4
• Type: CommonJS
• Main Entry: index.js
• Executable: gitlab-mcp-server
• Config Module: config/Config.js

Project Structure

gitlab-mcp-server/
├── index.js                          # Main entry file
├── config/                           # Config directory
│   └── Config.js                     # Centralized config file
├── lib/                              # Library directory
│   └── GitLabClient.js               # GitLab API client
├── package.json
└── README.md

Modular Design

• GitLabClient.js: Client class encapsulating GitLab API calls (root directory)
• config/Config.js: Centralized management for all configuration items (GitLab connection, client options, MCP Server config, Tools definitions)
• index.js: MCP Server main logic, handles tool invocations and request processing

Features

• User Management: Get current GitLab user information.
• Project Management: Search projects, get project ID mappings, and retrieve project details.
• Branch Management:
  • List repository branches.
  • Create new branches (supports specifying source branch/tag).
  • Delete branches.
• Merge Request (MR) Management:
  • Create MRs (supports standard creation and quick creation for public repositories).
  • Get MR status (including merge status, conflict detection).
  • Execute merge operations.
  • Close MRs.
  • Poll and wait for MR to become mergeable (supports timeout settings).

Configuration

All configuration items are centralized in lib/config/Config.js, customizable via environment variables:

Configure the following environment variables:

Variable	Description	Required	Default
GITLAB_URL	GitLab instance URL (e.g., https://gitlab.example.com)	Yes	-
GITLAB_PRIVATE_TOKEN	GitLab personal access token (Private Token)	Yes	-
TIMEOUT	Request timeout in milliseconds	No	10000
WAIT_INTERVAL	Polling interval in milliseconds	No	2000

Usage

As an MCP Server

Add to Claude Desktop configuration file:

Option 1: Using npx (Recommended)

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["@jesbrian/gitlab-mcp-server"],
      "env": {
        "GITLAB_URL": "https://your-gitlab-url.com",
        "GITLAB_PRIVATE_TOKEN": "your-private-token"
      }
    }
  }
}

Option 2: Local Path

Start the project locally first, then configure Claude Code:

# After cloning the project, enter the directory and install dependencies
cd gitlab-mcp-server
npm install

# Start the service locally (choose one method)
npm start              # Option 1: Use npm scripts
node index.js          # Option 2: Run directly
gitlab-mcp-server      # Option 3: Install globally and use command

Add to Claude Code MCP configuration:

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/path/to/gitlab-mcp-server/index.js"],
      "env": {
        "GITLAB_URL": "https://your-gitlab-url.com",
        "GITLAB_PRIVATE_TOKEN": "your-private-token"
      }
    }
  }
}

Available Tools

User & Project Management

• get_current_user: Get current GitLab user information.
• get_project_ids: Search projects by name and get project ID mappings (returns IDs across different namespaces).
• get_project: Get detailed information for a specified project.

Branch Operations

• get_repository_branches: List branches of a project.
• create_branch: Create a new branch (can specify source branch/tag, defaults to master).
• delete_branch: Delete a branch.

Merge Request (MR)

• create_merge_request: Create a merge request (supports custom title and description).
• create_merge_request_to_public: Quick tool that auto-detects personal and public repositories, creates MR from personal branch to public repository.
• merge_branch: Execute merge operation.
• get_merge_request_status: Get current MR status (including merge status, conflicts, etc.).
• close_merge_request: Close a merge request.
• wait_for_mergeable_status: Poll and wait for MR to become mergeable (supports timeout, default 5 minutes).