# Gitlab Mcp Server

> Gitlab MCP Server

- **Type:** MCP server
- **Install:** `agentstack add mcp-therealchristhomas-gitlab-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [TheRealChrisThomas](https://agentstack.voostack.com/s/therealchristhomas)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [TheRealChrisThomas](https://github.com/TheRealChrisThomas)
- **Source:** https://github.com/TheRealChrisThomas/gitlab-mcp-server

## Install

```sh
agentstack add mcp-therealchristhomas-gitlab-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](#installation)
  - [NPX (Recommended)](#npx-recommended)
  - [Global Installation](#global-installation)
- [Features](#features)
- [Group Milestones vs Project Milestones](#group-milestones-vs-project-milestones)
  - [Project Milestones](#project-milestones)
  - [Group Milestones](#group-milestones)
- [Group Milestone Examples](#group-milestone-examples)
  - [List Group Milestones](#list-group-milestones)
  - [Create Group Milestone](#create-group-milestone)
  - [Advanced Group Milestone Search](#advanced-group-milestone-search)
- [Practical Workflow: Finding Groups and Creating Milestones](#practical-workflow-finding-groups-and-creating-milestones)
  - [1. Search for Groups](#1-search-for-groups)
  - [2. List Existing Group Milestones](#2-list-existing-group-milestones)
  - [3. Create a Group Milestone](#3-create-a-group-milestone)
- [Tools](#tools)
  - [File Operations](#file-operations)
  - [Repository Management](#repository-management)
  - [Issue Management](#issue-management)
  - [Merge Request Management](#merge-request-management)
  - [Label Management](#label-management)
  - [Milestone Management](#milestone-management)
  - [Group Operations](#group-operations)
- [Setup](#setup)
  - [Personal Access Token](#personal-access-token)
  - [Usage with Claude Desktop](#usage-with-claude-desktop)
  - [Usage with Cursor/VSCode/Winsurf](#usage-with-cursorvscodewinsurf)
- [Environment Variables](#environment-variables)
- [Development](#development)
  - [Build](#build)
  - [Development Mode](#development-mode)
  - [Watch Mode](#watch-mode)
- [License](#license)

## Installation

### NPX (Recommended)

```bash
npx @therealchristhomas/gitlab-mcp-server
```

### Global Installation

```bash
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

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

### Create Group Milestone

```json
{
  "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

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

Based on the [GitLab Group Milestones API](https://docs.gitlab.com/api/group_milestones/), 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:

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

### 2. List Existing Group Milestones

Check what milestones already exist:

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

### 3. Create a Group Milestone

Create a milestone that spans multiple projects:

```json
{
  "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`

   - Create or update a single file in a project
   - Inputs:
     - `project_id` (string): Project ID or URL-encoded path
     - `file_path` (string): Path where to create/update the file
     - `content` (string): Content of the file
     - `commit_message` (string): Commit message
     - `branch` (string): Branch to create/update the file in
     - `previous_path` (optional string): Path of the file to move/rename
   - Returns: File content and commit details

2. `push_files`

   - Push multiple files in a single commit
   - Inputs:
     - `project_id` (string): Project ID or URL-encoded path
     - `branch` (string): Branch to push to
     - `files` (array): Files to push, each with `file_path` and `content`
     - `commit_message` (string): Commit message
   - Returns: Updated branch reference

3. `get_file_contents`

   - Get contents of a file or directory
   - Inputs:
     - `project_id` (string): Project ID or URL-encoded path
     - `file_path` (string): Path to file/directory
     - `ref` (optional string): Branch/tag/commit to get contents from
   - Returns: File/directory contents

### Repository Management

4. `search_repositories`

   - Search for GitLab projects
   - Inputs:
     - `search` (string): Search query
     - `page` (optional number): Page number for pagination
     - `per_page` (optional number): Results per page (default 20)
   - Returns: Project search results

5. `create_repository`

   - Create a new GitLab project
   - Inputs:
     - `name` (string): Project name
     - `description` (optional string): Project description
     - `visibility` (optional string): 'private', 'internal', or 'public'
     - `initialize_with_readme` (optional boolean): Initialize with README
   - Returns: Created project details

6. `fork_repository`

   - Fork a project
   - Inputs:
     - `project_id` (string): Project ID or URL-encoded path
     - `namespace` (optional string): Namespace to fork to
   - Returns: Forked project details

7. `create_branch`

   - Create a new branch
   - Inputs:
     - `project_id` (string): Project ID or URL-encoded path
     - `branch` (string): Name for new branch
     - `ref` (optional string): Source branch/commit for new branch
   - Returns: Created branch reference

### Group Operations

8. `search_groups`

   - Search for GitLab groups
   - Inputs:
     - `search` (string): Search query for groups
     - `page` (optional number): Page number for pagination
     - `per_page` (optional number): Results per page (default 20)
     - `owned` (optional boolean): Limit by groups owned by the current user
     - `min_access_level` (optional number): Minimum access level (10=Guest, 20=Reporter, 30=Developer, 40=Maintainer, 50=Owner)
   - Returns: Group search results

### Issue Management

9. `create_issue`

   - Create a new issue
   - Inputs:
     - `project_id` (string): Project ID or URL-encoded path
     - `title` (string): Issue title
     - `description` (optional string): Issue description
     - `assignee_ids` (optional number[]): User IDs to assign
     - `labels` (optional string[]): Labels to add
     - `milestone_id` (optional number): Milestone ID
   - Returns: Created issue details

10. `list_issues`

    - List all issues in a GitLab project
    - Inputs:
      - `project_id` (string): Project ID or URL-encoded path
      - `state` (optional string): 'opened', 'closed', or 'all'
      - `labels` (optional string): Comma-separated list of label names
      - `milestone` (optional string): Milestone title
      - `assignee_id` (optional number): User ID of assignee
      - `author_id` (optional number): User ID of author
      - `search` (optional string): Search against title and description
      - `created_after` (optional string): Return issues created after date (ISO 8601)
      - `created_before` (optional string): Return issues created before date (ISO 8601)
      - `updated_after` (optional string): Return issues updated after date (ISO 8601)
      - `updated_before` (optional string): Return issues updated before date (ISO 8601)
      - `sort` (optional string): Sort issues by various criteria
      - `order_by` (optional string): 'asc' or 'desc'
      - `page` (optional number): Page number for pagination
      - `per_page` (optional number): Results per page (default 20)
      - `with_labels_details` (optional boolean): If true, returns more details for each label. Default is false.
    - Returns: Array of issue objects

11. `update_issue`

    - Update an existing issue in a GitLab project
    - Inputs:
      - `project_id` (string): Project ID or URL-encoded path
      - `issue_iid` (number): Issue internal ID
      - `title` (optional string): New issue title
      - `description` (optional string): New issue description
      - `state_event` (optional string): 'close' or 'reopen'
      - `labels` (optional string[]): Array of label names
      - `assignee_ids` (optional number[]): Array of user IDs to assign
      - `milestone_id` (optional number): Milestone ID to assign
    - Returns: Updated issue details

12. `search_issues`

    - Search for issues in a GitLab project
    - Inputs:
      - `project_id` (string): Project ID or URL-encoded path
      - `search` (string): Search term for title and description
      - `state` (optional string): 'opened', 'closed', or 'all'
      - `labels` (optional string): Comma-separated list of label names
      - `page` (optional number): Page number for pagination
      - `per_page` (optional number): Results per page (default 20)
    - Returns: Array of matching issue objects

13. `add_issue_comment`

    - Add a comment to an issue in a GitLab project
    - Inputs:
      - `project_id` (string): Project ID or URL-encoded path
      - `issue_iid` (number): Issue internal ID
      - `body` (string): Content of the comment
    - Returns: Created comment details

### 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`

    - List all merge requests in a GitLab project
    - Inputs:
      - `project_id` (string): Project ID or URL-encoded path
      - `state` (optional string): 'opened', 'closed', 'locked', 'merged', or 'all'
      - `target_branch` (optional string): Filter by target branch
      - `source_branch` (optional string): Filter by source branch
      - `labels` (optional string): Comma-separated list of label names
      - `milestone` (optional string): Milestone title
      - `assignee_id` (optional number): User ID of assignee
      - `author_id` (optional number): User ID of author
      - `search` (optional string): Search against title and description
      - `created_after` (optional string): Return MRs created after date (ISO 8601)
      - `created_before` (optional string): Return MRs created before date (ISO 8601)
      - `updated_after` (optional string): Return MRs updated after date (ISO 8601)
      - `updated_before` (optional string): Return MRs updated before date (ISO 8601)
      - `sort` (optional string): Sort merge requests
      - `order_by` (optional string): 'asc' or 'desc'
      - `page` (optional number): Page number for pagination
      - `per_page` (optional number): Results per page (default 20)
    - Returns: Array of merge request objects

16. `update_merge_request`

    - Update an existing merge request in a GitLab project
    - Inputs:
      - `project_id` (string): Project ID or URL-encoded path
      - `merge_request_iid` (number): Merge request internal ID
      - `title` (optional string): New merge request title
      - `description` (optional string): New merge request description
      - `state_event` (optional string): 'close' or 'reopen'
      - `target_branch` (optional string): New target branch
      - `labels` (optional string[]): Array of label names
      - `assignee_ids` (optional number[]): Array of user IDs to assign
      - `milestone_id` (optional number): Milestone ID to assign
      - `remove_source_branch` (optional boolean): Remove source branch when merged
    - Returns: Updated merge request details

17. `merge_merge_request`

    - Merge a merge request in a GitLab project
    - Inputs:
      - `project_id` (string): Project ID or URL-encoded path
      - `merge_request_iid` (number): Merge request internal ID
      - `merge_commit_message` (optional string): Custom merge commit message
      - `should_remove_source_branch` (optional boolean): Remove source branch after merge
      - `merge_when_pipeline_succeeds` (optional boolean): Merge when pipeline succeeds
      - `sha` (optional string): SHA that must match the source branch HEAD
    - Returns: Merged merge request details

18. `add_merge_request_comment`

    - Add a comment to a merge request in a GitLab project
    - Inputs:
      - `project_id` (string): Project ID or URL-encoded path
      - `merge_request_iid` (number): Merge request internal ID
      - `body` (string): Content of the comment
    - Returns: Created comment details

### Label Management

19. `list_labels`

    - List all labels in a project
    - Inputs:
      - `project_id` (string): Project ID or URL-encoded path
      - `page` (optional number): Page number for pagination
      - `per_page` (optional number): Results per page (default 20)
    - Returns: Array of label objects

20. `create_label`

    - Create a new label
    - Inputs:
      - `project_id` (string): Project ID or URL-encoded path
      - `name` (string): Label name
      - `color` (string): Label color (hex code)
      - `description` (optional string): Label description
      - `priority` (optional number): Label priority
    - Returns: Created label details

21. `update_label`

    - Update an existing label
    - Inputs:
      - `project_id` (string): Project ID or URL-encoded path
      - `name` (string): Current label name
      - `new_name` (optional string): New label name
      - `color` (optional string): New label color
      - `description` (optional string): New label description
      - `priority` (optional number): New label priority
    - Returns: Updated label details

22. `delete_label`

    - Delete a label
    - Inputs:
      - `pr

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [TheRealChrisThomas](https://github.com/TheRealChrisThomas)
- **Source:** [TheRealChrisThomas/gitlab-mcp-server](https://github.com/TheRealChrisThomas/gitlab-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-therealchristhomas-gitlab-mcp-server
- Seller: https://agentstack.voostack.com/s/therealchristhomas
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.