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
- Features
- Group Milestones vs Project Milestones
- Group Milestone Examples
- Practical Workflow: Finding Groups and Creating Milestones
- Tools
- Setup
- Environment Variables
- Development
- 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-webappproject
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, andmy-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 pathfile_path(string): Path where to create/update the filecontent(string): Content of the filecommit_message(string): Commit messagebranch(string): Branch to create/update the file inprevious_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 pathbranch(string): Branch to push tofiles(array): Files to push, each withfile_pathandcontentcommit_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 pathfile_path(string): Path to file/directoryref(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 querypage(optional number): Page number for paginationper_page(optional number): Results per page (default 20)
- Returns: Project search results
-
create_repository- Create a new GitLab project
- Inputs:
name(string): Project namedescription(optional string): Project descriptionvisibility(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 pathnamespace(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 pathbranch(string): Name for new branchref(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 groupspage(optional number): Page number for paginationper_page(optional number): Results per page (default 20)owned(optional boolean): Limit by groups owned by the current usermin_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 pathtitle(string): Issue titledescription(optional string): Issue descriptionassignee_ids(optional number[]): User IDs to assignlabels(optional string[]): Labels to addmilestone_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 pathstate(optional string): 'opened', 'closed', or 'all'labels(optional string): Comma-separated list of label namesmilestone(optional string): Milestone titleassignee_id(optional number): User ID of assigneeauthor_id(optional number): User ID of authorsearch(optional string): Search against title and descriptioncreated_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 criteriaorder_by(optional string): 'asc' or 'desc'page(optional number): Page number for paginationper_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 pathissue_iid(number): Issue internal IDtitle(optional string): New issue titledescription(optional string): New issue descriptionstate_event(optional string): 'close' or 'reopen'labels(optional string[]): Array of label namesassignee_ids(optional number[]): Array of user IDs to assignmilestone_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 pathsearch(string): Search term for title and descriptionstate(optional string): 'opened', 'closed', or 'all'labels(optional string): Comma-separated list of label namespage(optional number): Page number for paginationper_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 pathissue_iid(number): Issue internal IDbody(string): Content of the comment
- Returns: Created comment details
Merge Request Management
create_merge_request
- Create a new merge request
- Inputs:
project_id(string): Project ID or URL-encoded pathtitle(string): MR titledescription(optional string): MR descriptionsource_branch(string): Branch containing changestarget_branch(string): Branch to merge intodraft(optional boolean): Create as draft MRallow_collaboration(optional boolean): Allow commits from upstream members
- Returns: Created merge request details
-
list_merge_requests- List all merge requests in a GitLab project
- Inputs:
project_id(string): Project ID or URL-encoded pathstate(optional string): 'opened', 'closed', 'locked', 'merged', or 'all'target_branch(optional string): Filter by target branchsource_branch(optional string): Filter by source branchlabels(optional string): Comma-separated list of label namesmilestone(optional string): Milestone titleassignee_id(optional number): User ID of assigneeauthor_id(optional number): User ID of authorsearch(optional string): Search against title and descriptioncreated_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 requestsorder_by(optional string): 'asc' or 'desc'page(optional number): Page number for paginationper_page(optional number): Results per page (default 20)
- Returns: Array of merge request objects
-
update_merge_request- Update an existing merge request in a GitLab project
- Inputs:
project_id(string): Project ID or URL-encoded pathmerge_request_iid(number): Merge request internal IDtitle(optional string): New merge request titledescription(optional string): New merge request descriptionstate_event(optional string): 'close' or 'reopen'target_branch(optional string): New target branchlabels(optional string[]): Array of label namesassignee_ids(optional number[]): Array of user IDs to assignmilestone_id(optional number): Milestone ID to assignremove_source_branch(optional boolean): Remove source branch when merged
- Returns: Updated merge request details
-
merge_merge_request- Merge a merge request in a GitLab project
- Inputs:
project_id(string): Project ID or URL-encoded pathmerge_request_iid(number): Merge request internal IDmerge_commit_message(optional string): Custom merge commit messageshould_remove_source_branch(optional boolean): Remove source branch after mergemerge_when_pipeline_succeeds(optional boolean): Merge when pipeline succeedssha(optional string): SHA that must match the source branch HEAD
- Returns: Merged merge request details
-
add_merge_request_comment- Add a comment to a merge request in a GitLab project
- Inputs:
project_id(string): Project ID or URL-encoded pathmerge_request_iid(number): Merge request internal IDbody(string): Content of the comment
- Returns: Created comment details
Label Management
-
list_labels- List all labels in a project
- Inputs:
project_id(string): Project ID or URL-encoded pathpage(optional number): Page number for paginationper_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 pathname(string): Label namecolor(string): Label color (hex code)description(optional string): Label descriptionpriority(optional number): Label priority
- Returns: Created label details
-
update_label- Update an existing label
- Inputs:
project_id(string): Project ID or URL-encoded pathname(string): Current label namenew_name(optional string): New label namecolor(optional string): New label colordescription(optional string): New label descriptionpriority(optional number): New label priority
- Returns: Updated label details
-
delete_label- Delete a label
- Inputs:
project_id(string): Project ID or URL-encoded pathname(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 pathstate(optional string): 'active' or 'closed'page(optional number): Page number for paginationper_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 pathtitle(string): Milestone titledescription(optional string): Milestone descriptiondue_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 pathmilestone_id(number): Milestone IDtitle(optional string): New titledescription(optional string): New descriptiondue_date(optional string): New due datestart_date(optional string): New start datestate_event(optional string): 'close' or 'activate'
- Returns: Updated milestone details
-
delete_milestone- Delete a milestone
- Inputs:
project_id(string): Project ID or URL-encoded pathmilestone_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 pathstate(optional string): 'active' or 'closed'title(optional string): Filter by milestone title (case-sensitive)search(optional string): Search in title or descriptionsearch_title(optional string): Search in title onlyinclude_ancestors(optional boolean): Include parent group milestonesinclude_descendants(optional boolean): Include subgroup milestonesupdated_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 datestart_date(optional string): Filter where due_date >= start_dateend_date(optional string): Filter where start_date <= end_datepage(optional number): Page number for paginationper_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 pathtitle(string): Milestone titledescription(optional string): Milestone descriptiondue_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 pathmilestone_id(number): Milestone IDtitle(optional string): New titledescription(optional string): New descriptiondue_date(optional string): New due datestart_date(optional string): New start datestate_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 pathmilestone_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:
apifor full API accessread_apifor read-only accessread_repositoryandwrite_repositoryfor 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 tohttps://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.