Model Context Protocol server for GitLab integration
npm install gitlab-mcpModel Context Protocol (MCP) server for GitLab integration. This server allows communication between GitLab and MCP-compatible AI assistants.
When using with the Claude App, you need to set up your API key and URLs directly.
``json`
{
"mcpServers": {
"GitLab communication server": {
"command": "npx",
"args": ["-y", "mcp-gitlab"],
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "your_gitlab_token",
"GITLAB_API_URL": "your_gitlab_api_url",
"GITLAB_READ_ONLY_MODE": "true"
}
}
}
}
- GITLAB_PERSONAL_ACCESS_TOKEN: Your GitLab personal access token.GITLAB_API_URL
- : Your GitLab API URL. (Default: https://gitlab.com/api/v4)GITLAB_READ_ONLY_MODE
- : When set to 'true', restricts the server to only expose read-only operations. Useful for enhanced security or when write access is not needed. Also useful for using with Cursor and it's 40 tool limit.
1. create_or_update_file
- Create or update a single file in a GitLab project. đ
- Inputs:
- project_id (string): Project ID or namespace/project_pathfile_path
- (string): Path to create/update the filecontent
- (string): File contentcommit_message
- (string): Commit messagebranch
- (string): Branch to create/update the file inprevious_path
- (optional string): Previous file path when renaming a file
- Returns: File content and commit details
2. push_files
- Push multiple files in a single commit. đ¤
- Inputs:
- project_id (string): Project ID or namespace/project_pathbranch
- (string): Branch to push tofiles
- (array): Array of files to push, each with file_path and content propertiescommit_message
- (string): Commit message
- Returns: Updated branch reference
3. search_repositories
- Search for GitLab projects. đ
- Inputs:
- search (string): Search querypage
- (optional number): Page number (default: 1)per_page
- (optional number): Results per page (default: 20, max: 100)
- Returns: Project search results
4. create_repository
- Create a new GitLab project. â
- Inputs:
- name (string): Project namedescription
- (optional string): Project descriptionvisibility
- (optional string): Project visibility level (public, private, internal)initialize_with_readme
- (optional boolean): Initialize with README
- Returns: Details of the created project
5. get_file_contents
- Get the contents of a file or directory. đ
- Inputs:
- project_id (string): Project ID or namespace/project_pathfile_path
- (string): Path to the file/directoryref
- (optional string): Branch, tag, or commit SHA (default: default branch)
- Returns: File/directory content
6. create_issue
- Create a new issue. đ
- Inputs:
- project_id (string): Project ID or namespace/project_pathtitle
- (string): Issue titledescription
- (string): Issue descriptionassignee_ids
- (optional number[]): Array of assignee IDsmilestone_id
- (optional number): Milestone IDlabels
- (optional string[]): Array of labels
- Returns: Details of the created issue
7. create_merge_request
- Create a new merge request. đ
- Inputs:
- project_id (string): Project ID or namespace/project_pathtitle
- (string): Merge request titledescription
- (string): Merge request descriptionsource_branch
- (string): Branch with changestarget_branch
- (string): Branch to merge intoallow_collaboration
- (optional boolean): Allow collaborators to push commits to the source branchdraft
- (optional boolean): Create as a draft merge request
- Returns: Details of the created merge request
8. fork_repository
- Fork a project. đ´
- Inputs:
- project_id (string): Project ID or namespace/project_path to forknamespace
- (optional string): Namespace to fork into (default: user namespace)
- Returns: Details of the forked project
9. create_branch
- Create a new branch. đŋ
- Inputs:
- project_id (string): Project ID or namespace/project_pathname
- (string): New branch nameref
- (optional string): Ref to create the branch from (branch, tag, commit SHA, default: default branch)
- Returns: Created branch reference
10. get_merge_request
- Get details of a merge request. âšī¸
- Inputs:
- project_id (string): Project ID or namespace/project_pathmerge_request_iid
- (number): Merge request IID
- Returns: Merge request details
11. get_merge_request_diffs
- Get changes (diffs) of a merge request. diff
- Inputs:
- project_id (string): Project ID or namespace/project_pathmerge_request_iid
- (number): Merge request IIDview
- (optional string): Diff view type ('inline' or 'parallel')
- Returns: Array of merge request diff information
12. update_merge_request
- Update a merge request. đ
- Inputs:
- project_id (string): Project ID or namespace/project_pathmerge_request_iid
- (number): Merge request IIDtitle
- (optional string): New titledescription
- (string): New descriptiontarget_branch
- (optional string): New target branchstate_event
- (optional string): Merge request state change event ('close', 'reopen')remove_source_branch
- (optional boolean): Remove source branch after mergeallow_collaboration
- (optional boolean): Allow collaborators to push commits to the source branch
- Returns: Updated merge request details
13. create_note
- Create a new note (comment) to an issue or merge request. đŦ
- Inputs:
- project_id (string): Project ID or namespace/project_pathnoteable_type
- (string): Type of noteable ("issue" or "merge_request")noteable_iid
- (number): IID of the issue or merge requestbody
- (string): Note content
- Returns: Details of the created note
14. list_projectssearch
- List accessible projects with rich filtering options đ
- Inputs:
- Search/filtering:
- owned
- membership
- archived
- visibility
- with_issues_enabled
- Features filtering:
- with_merge_requests_enabled
- order_by
- Sorting:
- sort
- min_access_level
- Access control:
- page
- Pagination:
- per_page
- simple
- list_labels
- Returns: Array of projects
15. project_id
- List all labels for a project with filtering options đˇī¸
- Inputs:
- (string): Project ID or pathwith_counts
- (optional): Include issue and merge request countsinclude_ancestor_groups
- (optional): Include ancestor groupssearch
- (optional): Filter labels by keywordget_label
- Returns: Array of labels
16. project_id
- Get a single label from a project
- Inputs:
- (string): Project ID or pathlabel_id
- (number/string): Label ID or nameinclude_ancestor_groups
- (optional): Include ancestor groupscreate_label
- Returns: label details
17. project_id
- Create a new label in an object đˇī¸â
- Inputs:
- (string): Project ID or pathname
- (string): Label namecolor
- (string): Color in hex format (e.g., "#FF0000")description
- (optional): Label descriptionpriority
- (optional): Label priorityupdate_label
- Returns: Created label details
18. project_id
- Update an existing label in a project đˇī¸âī¸
- Inputs:
- (string): Project ID or pathlabel_id
- (number/string): Label ID or namenew_name
- (optional): New label namecolor
- (optional): New color in hex formatdescription
- (optional): New descriptionpriority
- (optional): New prioritydelete_label
- Returns: Updated label details
19.
- Delete a label from a project đˇī¸â
- Inputs:
- project_id (string): Project ID or pathlabel_id
- (number/string): Label ID or name
- Returns: Success message
20. list_group_projects
- List all projects in a GitLab group. đ
- Inputs:
- group_id (string): Project ID or namespace/project_pathinclude_subgroups
- Filtering options:
- (optional boolean): Include projects from subgroupssearch
- (optional string): Search term to filter projectsarchived
- (optional boolean): Filter for archived projectsvisibility
- (optional string): Filter by project visibility (public/internal/private)with_programming_language
- (optional string): Filter by programming languagestarred
- (optional boolean): Filter by starred projectswith_issues_enabled
- Feature filtering:
- (optional boolean): Filter projects with issues feature enabledwith_merge_requests_enabled
- (optional boolean): Filter projects with merge requests feature enabledmin_access_level
- (optional number): Filter by minimum access levelpage
- Pagination:
- (optional number): Page numberper_page
- (optional number): Results per pageorder_by
- Sorting:
- (optional string): Field to sort bysort
- (optional string): Sort direction (asc/desc)statistics
- Additional data:
- (optional boolean): Include project statisticswith_custom_attributes
- (optional boolean): Include custom attributeswith_security_reports
- (optional boolean): Include security reports
- Returns: List of projects
Before running the server, you need to set the following environment variables:
```
GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token
GITLAB_API_URL=your_gitlab_api_url # Default: https://gitlab.com/api/v4
GITLAB_READ_ONLY_MODE=true # Optional: Enable read-only mode
- Model Context Protocol
- GitLab MCP
MIT