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)
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
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
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
- 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
Label Management
-
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
-
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
-
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
-
delete_label
- Delete a label
- Inputs:
project_id
(string): Project ID or URL-encoded path
name
(string): Label name to delete
- Returns: Success confirmation
Milestone Management
-
list_milestones
- List all milestones in a project
- Inputs:
project_id
(string): Project ID or URL-encoded path
state
(optional string): 'active' or 'closed'
page
(optional number): Page number for pagination
per_page
(optional number): Results per page (default 20)
- Returns: Array of milestone objects
-
create_milestone
- Create a new milestone
- Inputs:
project_id
(string): Project ID or URL-encoded path
title
(string): Milestone title
description
(optional string): Milestone description
due_date
(optional string): Due date (YYYY-MM-DD)
start_date
(optional string): Start date (YYYY-MM-DD)
- Returns: Created milestone details
-
update_milestone
- Update an existing milestone
- Inputs:
project_id
(string): Project ID or URL-encoded path
milestone_id
(number): Milestone ID
title
(optional string): New title
description
(optional string): New description
due_date
(optional string): New due date
start_date
(optional string): New start date
state_event
(optional string): 'close' or 'activate'
- Returns: Updated milestone details
-
delete_milestone
- Delete a milestone
- Inputs:
project_id
(string): Project ID or URL-encoded path
milestone_id
(number): Milestone ID to delete
- Returns: Success confirmation
-
list_group_milestones
- List all milestones in a GitLab group
- Inputs:
group_id
(string): Group ID or URL-encoded path
state
(optional string): 'active' or 'closed'
title
(optional string): Filter by milestone title (case-sensitive)
search
(optional string): Search in title or description
search_title
(optional string): Search in title only
include_ancestors
(optional boolean): Include parent group milestones
include_descendants
(optional boolean): Include subgroup milestones
updated_before
(optional string): Filter by update date (ISO 8601)
updated_after
(optional string): Filter by update date (ISO 8601)
containing_date
(optional string): Milestones containing given date
start_date
(optional string): Filter where due_date >= start_date
end_date
(optional string): Filter where start_date <= end_date
page
(optional number): Page number for pagination
per_page
(optional number): Results per page (default 20)
- Returns: Array of group milestone objects
-
create_group_milestone
- Create a new milestone in a GitLab group
- Inputs:
group_id
(string): Group ID or URL-encoded path
title
(string): Milestone title
description
(optional string): Milestone description
due_date
(optional string): Due date (YYYY-MM-DD)
start_date
(optional string): Start date (YYYY-MM-DD)
- Returns: Created group milestone details
-
update_group_milestone
- Update an existing milestone in a GitLab group
- Inputs:
group_id
(string): Group ID or URL-encoded path
milestone_id
(number): Milestone ID
title
(optional string): New title
description
(optional string): New description
due_date
(optional string): New due date
start_date
(optional string): New start date
state_event
(optional string): 'close' or 'activate'
- Returns: Updated group milestone details
-
delete_group_milestone
- Delete a milestone from a GitLab group
- Inputs:
group_id
(string): Group ID or URL-encoded path
milestone_id
(number): Milestone ID to delete
- Returns: Success confirmation
Setup
Personal Access Token
Create a GitLab Personal Access Token with appropriate permissions:
- Go to User Settings > Access Tokens in GitLab
- 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": "<YOUR_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": "<YOUR_TOKEN>",
"GITLAB_API_URL": "https://gitlab.com/api/v4"
}
}
}
}
Note: Replace <YOUR_TOKEN>
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.