GitLab MCP Server

MCP Server for the GitLab API, enabling project management, file operations, and more. Forked from https://github.com/modelcontextprotocol

Table of Contents

• Installation
  • NPX (Recommended)
  • Global Installation
• Features
• Group Milestones vs Project Milestones
  • Project Milestones
  • Group Milestones
• Group Milestone Examples
  • List Group Milestones
  • Create Group Milestone
  • Advanced Group Milestone Search
• Practical Workflow: Finding Groups and Creating Milestones
  • 1. Search for Groups
  • 2. List Existing Group Milestones
  • 3. Create a Group Milestone
• Tools
  • File Operations
  • Repository Management
  • Issue Management
  • Merge Request Management
  • Label Management
  • Milestone Management
  • Group Operations
• Setup
  • Personal Access Token
  • Usage with Claude Desktop
  • Usage with Cursor/VSCode/Winsurf
• Environment Variables
• Development
  • Build
  • Development Mode
  • Watch Mode
• License

Installation

NPX (Recommended)

npx @therealchristhomas/gitlab-mcp-server

Global Installation

npm install -g @therealchristhomas/gitlab-mcp-server
gitlab-mcp

Features

• Automatic Branch Creation: When creating/updating files or pushing changes, branches are automatically created if they don't exist
• Comprehensive Error Handling: Clear error messages for common issues
• Git History Preservation: Operations maintain proper Git history without force pushing
• Batch Operations: Support for both single-file and multi-file operations
• Project Workflow Management: Label and milestone management for better project organization
• Repository Management: Search, create, and fork GitLab projects
• File Operations: Create, update, and retrieve file contents
• Branch Management: Create branches and manage repository structure
• Issue Management: Create, list, update, search, and comment on issues
• Merge Request Management: List, update, merge, and comment on merge requests
• Label Management: Create, update, and delete project labels
• Project Milestones: Create, update, and delete project-level milestones
• Group Milestones: Create, update, and delete group-level milestones that span multiple projects

Group Milestones vs Project Milestones

This server supports both project milestones and group milestones:

Project Milestones

• Scoped to a single project
• Use tools: `list_milestones`, `create_milestone`, `update_milestone`, `delete_milestone`
• Example: Track features for `my-webapp` project

Group Milestones

• Span multiple projects within a group
• Use tools: `list_group_milestones`, `create_group_milestone`, `update_group_milestone`, `delete_group_milestone`
• Support advanced filtering with `include_ancestors`, `include_descendants`
• Example: Track a release across `my-webapp`, `my-api`, and `my-admin`

Group Milestone Examples

List Group Milestones

{
  "group_id": "my-organization",
  "state": "active",
  "include_descendants": true
}

Create Group Milestone

{
  "group_id": "my-organization",
  "title": "Q1 2025 Release",
  "description": "Major feature release including new tools and performance improvements",
  "due_date": "2025-03-31",
  "start_date": "2025-01-01"
}

Advanced Group Milestone Search

{
  "group_id": "my-organization/core",
  "search": "release",
  "include_ancestors": true,
  "updated_after": "2024-01-01T00:00:00Z"
}

Based on the GitLab Group Milestones API, group milestones are ideal for coordinating releases and features across multiple projects in your organization.

Practical Workflow: Finding Groups and Creating Milestones

Here's a typical workflow for working with group milestones:

1. Search for Groups

First, find the group you want to work with:

{
  "search": "my-organization",
  "owned": true
}

2. List Existing Group Milestones

Check what milestones already exist:

{
  "group_id": "my-organization",
  "state": "active"
}

3. Create a Group Milestone

Create a milestone that spans multiple projects:

{
  "group_id": "my-organization",
  "title": "Q1 2025 Release",
  "description": "Cross-project release including webapp, API, and admin features",
  "due_date": "2025-03-31"
}

This workflow is especially useful for large organizations with multiple related projects under the same group.

Tools

File Operations

1. `create_or_update_file`

2. `push_files`

3. `get_file_contents`

Repository Management

4. `search_repositories`

5. `create_repository`

6. `fork_repository`

7. `create_branch`

Group Operations

8. `search_groups`

Issue Management

9. `create_issue`

10. `list_issues`

11. `update_issue`

12. `search_issues`

13. `add_issue_comment`

Merge Request Management

14. `create_merge_request`

• Create a new merge request
• Inputs:
  • `project_id` (string): Project ID or URL-encoded path
  • `title` (string): MR title
  • `description` (optional string): MR description
  • `source_branch` (string): Branch containing changes
  • `target_branch` (string): Branch to merge into
  • `draft` (optional boolean): Create as draft MR
  • `allow_collaboration` (optional boolean): Allow commits from upstream members
• Returns: Created merge request details

15. `list_merge_requests`

16. `update_merge_request`

17. `merge_merge_request`

18. `add_merge_request_comment`

Label Management

19. `list_labels`

20. `create_label`

21. `update_label`

22. `delete_label`

Milestone Management

23. `list_milestones`

24. `create_milestone`

25. `update_milestone`

26. `delete_milestone`

27. `list_group_milestones`

• Select the required scopes:
  • `api` for full API access
  • `read_api` for read-only access
  • `read_repository` and `write_repository` for repository operations
• Create the token and save it securely

Usage with Claude Desktop

Add the following to your `claude_desktop_config.json`:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@therealchristhomas/gitlab-mcp-server"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

Usage with Cursor/VSCode/Winsurf

Add the following to your MCP configuration:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@therealchristhomas/gitlab-mcp-server"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

Note: Replace `` with your actual GitLab Personal Access Token. Also, replace with your Gitlab API URL if you're not using gitlab.com

Environment Variables

• `GITLAB_PERSONAL_ACCESS_TOKEN`: Your GitLab personal access token (required)
• `GITLAB_API_URL`: Base URL for GitLab API (optional, defaults to `https://gitlab.com/api/v4`)

For self-hosted GitLab instances, update the `GITLAB_API_URL` to point to your instance:

"GITLAB_API_URL": "https://your-gitlab-instance.com/api/v4"

Development

Build

npm run build

Development Mode

npm run dev

Watch Mode

npm run watch

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.