GitLab MCP Server

1# GitLab MCP Server
2 
3MCP Server for the GitLab API, enabling project management, file operations, and more.
4 
5### Features
6 
7- **Automatic Branch Creation**: When creating/updating files or pushing changes, branches are automatically created if they don't exist
8- **Comprehensive Error Handling**: Clear error messages for common issues
9- **Git History Preservation**: Operations maintain proper Git history without force pushing
10- **Batch Operations**: Support for both single-file and multi-file operations
11 
12 
13## Tools
14 
151. `create_or_update_file`
16   - Create or update a single file in a project
17   - Inputs:
18     - `project_id` (string): Project ID or URL-encoded path
19     - `file_path` (string): Path where to create/update the file
20     - `content` (string): Content of the file
21     - `commit_message` (string): Commit message
22     - `branch` (string): Branch to create/update the file in
23     - `previous_path` (optional string): Path of the file to move/rename
24   - Returns: File content and commit details
25 
262. `push_files`
27   - Push multiple files in a single commit
28   - Inputs:
29     - `project_id` (string): Project ID or URL-encoded path
30     - `branch` (string): Branch to push to
31     - `files` (array): Files to push, each with `file_path` and `content`
32     - `commit_message` (string): Commit message
33   - Returns: Updated branch reference
34 
353. `search_repositories`
36   - Search for GitLab projects
37   - Inputs:
38     - `search` (string): Search query
39     - `page` (optional number): Page number for pagination
40     - `per_page` (optional number): Results per page (default 20)
41   - Returns: Project search results
42 
434. `create_repository`
44   - Create a new GitLab project
45   - Inputs:
46     - `name` (string): Project name
47     - `description` (optional string): Project description
48     - `visibility` (optional string): 'private', 'internal', or 'public'
49     - `initialize_with_readme` (optional boolean): Initialize with README
50   - Returns: Created project details
51 
525. `get_file_contents`
53   - Get contents of a file or directory
54   - Inputs:
55     - `project_id` (string): Project ID or URL-encoded path
56     - `file_path` (string): Path to file/directory
57     - `ref` (optional string): Branch/tag/commit to get contents from
58   - Returns: File/directory contents
59 
606. `create_issue`
61   - Create a new issue
62   - Inputs:
63     - `project_id` (string): Project ID or URL-encoded path
64     - `title` (string): Issue title
65     - `description` (optional string): Issue description
66     - `assignee_ids` (optional number[]): User IDs to assign
67     - `labels` (optional string[]): Labels to add
68     - `milestone_id` (optional number): Milestone ID
69   - Returns: Created issue details
70 
717. `create_merge_request`
72   - Create a new merge request
73   - Inputs:
74     - `project_id` (string): Project ID or URL-encoded path
75     - `title` (string): MR title
76     - `description` (optional string): MR description
77     - `source_branch` (string): Branch containing changes
78     - `target_branch` (string): Branch to merge into
79     - `draft` (optional boolean): Create as draft MR
80     - `allow_collaboration` (optional boolean): Allow commits from upstream members
81   - Returns: Created merge request details
82 
838. `fork_repository`
84   - Fork a project
85   - Inputs:
86     - `project_id` (string): Project ID or URL-encoded path
87     - `namespace` (optional string): Namespace to fork to
88   - Returns: Forked project details
89 
909. `create_branch`
91   - Create a new branch
92   - Inputs:
93     - `project_id` (string): Project ID or URL-encoded path
94     - `branch` (string): Name for new branch
95     - `ref` (optional string): Source branch/commit for new branch
96   - Returns: Created branch reference
97 
98## Setup
99 
100### Personal Access Token
101[Create a GitLab Personal Access Token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) with appropriate permissions:
102   - Go to User Settings > Access Tokens in GitLab
103   - Select the required scopes:
104     - `api` for full API access
105     - `read_api` for read-only access
106     - `read_repository` and `write_repository` for repository operations
107   - Create the token and save it securely
108 
109### Usage with Claude Desktop
110Add the following to your `claude_desktop_config.json`:
111 
112#### Docker
113```json
114{
115  "mcpServers": { 
116    "gitlab": {
117      "command": "docker",
118      "args": [
119        "run",
120        "--rm",
121        "-i",
122        "-e",
123        "GITLAB_PERSONAL_ACCESS_TOKEN",
124        "-e",
125        "GITLAB_API_URL",
126        "mcp/gitlab"
127      ],
128      "env": {
129        "GITLAB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>",
130        "GITLAB_API_URL": "https://gitlab.com/api/v4" // Optional, for self-hosted instances
131      }
132    }
133  }
134}
135```
136 
137#### NPX
138 
139```json
140{
141  "mcpServers": {
142    "gitlab": {
143      "command": "npx",
144      "args": [
145        "-y",
146        "@modelcontextprotocol/server-gitlab"
147      ],
148      "env": {
149        "GITLAB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>",
150        "GITLAB_API_URL": "https://gitlab.com/api/v4" // Optional, for self-hosted instances
151      }
152    }
153  }
154}
155```
156 
157### Usage with VS Code
158 
159For quick installation, use one of the one-click installation buttons below...
160 
161[![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-NPM-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=gitlab&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gitlab_token%22%2C%22description%22%3A%22GitLab%20Personal%20Access%20Token%22%2C%22password%22%3Atrue%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gitlab_url%22%2C%22description%22%3A%22GitLab%20API%20URL%20(optional%2C%20default%3A%20https%3A%2F%2Fgitlab.com%2Fapi%2Fv4)%22%2C%22default%22%3A%22https%3A%2F%2Fgitlab.com%2Fapi%2Fv4%22%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-gitlab%22%5D%2C%22env%22%3A%7B%22GITLAB_PERSONAL_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agitlab_token%7D%22%2C%22GITLAB_API_URL%22%3A%22%24%7Binput%3Agitlab_url%7D%22%7D%7D) [![Install with NPX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-NPM-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=gitlab&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gitlab_token%22%2C%22description%22%3A%22GitLab%20Personal%20Access%20Token%22%2C%22password%22%3Atrue%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gitlab_url%22%2C%22description%22%3A%22GitLab%20API%20URL%20(optional%2C%20default%3A%20https%3A%2F%2Fgitlab.com%2Fapi%2Fv4)%22%2C%22default%22%3A%22https%3A%2F%2Fgitlab.com%2Fapi%2Fv4%22%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-gitlab%22%5D%2C%22env%22%3A%7B%22GITLAB_PERSONAL_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agitlab_token%7D%22%2C%22GITLAB_API_URL%22%3A%22%24%7Binput%3Agitlab_url%7D%22%7D%7D&quality=insiders)
162 
163[![Install with Docker in VS Code](https://img.shields.io/badge/VS_Code-Docker-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=gitlab&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gitlab_token%22%2C%22description%22%3A%22GitLab%20Personal%20Access%20Token%22%2C%22password%22%3Atrue%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gitlab_url%22%2C%22description%22%3A%22GitLab%20API%20URL%20(optional%2C%20default%3A%20https%3A%2F%2Fgitlab.com%2Fapi%2Fv4)%22%2C%22default%22%3A%22https%3A%2F%2Fgitlab.com%2Fapi%2Fv4%22%7D%5D&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22--rm%22%2C%22-i%22%2C%22mcp%2Fgitlab%22%5D%2C%22env%22%3A%7B%22GITLAB_PERSONAL_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agitlab_token%7D%22%2C%22GITLAB_API_URL%22%3A%22%24%7Binput%3Agitlab_url%7D%22%7D%7D) [![Install with Docker in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Docker-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=gitlab&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gitlab_token%22%2C%22description%22%3A%22GitLab%20Personal%20Access%20Token%22%2C%22password%22%3Atrue%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gitlab_url%22%2C%22description%22%3A%22GitLab%20API%20URL%20(optional%2C%20default%3A%20https%3A%2F%2Fgitlab.com%2Fapi%2Fv4)%22%2C%22default%22%3A%22https%3A%2F%2Fgitlab.com%2Fapi%2Fv4%22%7D%5D&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22--rm%22%2C%22-i%22%2C%22mcp%2Fgitlab%22%5D%2C%22env%22%3A%7B%22GITLAB_PERSONAL_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agitlab_token%7D%22%2C%22GITLAB_API_URL%22%3A%22%24%7Binput%3Agitlab_url%7D%22%7D%7D&quality=insiders)
164 
165For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`.
166 
167Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
168 
169> Note that the `mcp` key is not needed in the `.vscode/mcp.json` file.
170 
171#### Docker
172 
173```json
174{
175  "mcp": {
176    "inputs": [
177      {
178        "type": "promptString",
179        "id": "gitlab_token",
180        "description": "GitLab Personal Access Token",
181        "password": true
182      },
183      {
184        "type": "promptString",
185        "id": "gitlab_url",
186        "description": "GitLab API URL (optional)",
187        "default": "https://gitlab.com/api/v4"
188      }
189    ],
190    "servers": {
191      "gitlab": {
192        "command": "docker",
193        "args": [
194          "run",
195          "--rm",
196          "-i",
197          "mcp/gitlab"
198        ],
199        "env": {
200          "GITLAB_PERSONAL_ACCESS_TOKEN": "${input:gitlab_token}",
201          "GITLAB_API_URL": "${input:gitlab_url}"
202        }
203      }
204    }
205  }
206}
207```
208 
209#### NPX
210 
211```json
212{
213  "mcp": {
214    "inputs": [
215      {
216        "type": "promptString",
217        "id": "gitlab_token",
218        "description": "GitLab Personal Access Token",
219        "password": true
220      },
221      {
222        "type": "promptString",
223        "id": "gitlab_url",
224        "description": "GitLab API URL (optional)",
225        "default": "https://gitlab.com/api/v4"
226      }
227    ],
228    "servers": {
229      "gitlab": {
230        "command": "npx",
231        "args": [
232          "-y",
233          "@modelcontextprotocol/server-gitlab"
234        ],
235        "env": {
236          "GITLAB_PERSONAL_ACCESS_TOKEN": "${input:gitlab_token}",
237          "GITLAB_API_URL": "${input:gitlab_url}"
238        }
239      }
240    }
241  }
242}
243```
244 
245## Build
246 
247Docker build:
248 
249```bash
250docker build -t vonwig/gitlab:mcp -f src/gitlab/Dockerfile .
251```
252 
253## Environment Variables
254 
255- `GITLAB_PERSONAL_ACCESS_TOKEN`: Your GitLab personal access token (required)
256- `GITLAB_API_URL`: Base URL for GitLab API (optional, defaults to `https://gitlab.com/api/v4`)
257 
258## License
259 
260This 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.
261