Content
# gitlab-mcp-server
MCP server for managing GitLab repositories — merge requests, pipelines, branches, and file operations — over the [Model Context Protocol](https://modelcontextprotocol.io).
## Features
- **Merge Requests** — create, list, get, review diffs, and comment
- **Pipelines** — list, get, retry, and cancel
- **Branches** — create, delete, list, and inspect
- **Files** — push (create/update/delete/move) and read file contents
- **Enterprise support** — works with any GitLab instance (set `GITLAB_URL`)
## Installation
```bash
pip install gitlab-mcp-server
```
Or install from source:
```bash
git clone https://github.com/hhldiniz/gitlabmcp.git
cd gitlabmcp
pip install -e .
```
For tests:
```bash
pip install -e ".[test]"
```
## Configuration
Set the following environment variables:
| Variable | Required | Default | Description |
|---|---|---|---|
| `GITLAB_TOKEN` | Yes | — | GitLab Personal Access Token |
| `GITLAB_URL` | No | `https://gitlab.com` | GitLab instance URL |
## Usage
### Run as a standalone MCP server (stdio)
```bash
export GITLAB_TOKEN=glpat-your-token
python -m gitlab_mcp_server
```
### Configure with an MCP client
Add to your MCP client config (e.g. `claude_desktop_config.json`):
```json
{
"mcpServers": {
"gitlab": {
"command": "python",
"args": ["-m", "gitlab_mcp_server"],
"env": {
"GITLAB_TOKEN": "glpat-your-token",
"GITLAB_URL": "https://gitlab.com"
}
}
}
}
```
## Tools
| Tool | Description |
|---|---|
| `create_mr` | Create a merge request |
| `list_mrs` | List merge requests (filter by state) |
| `get_mr` | Get merge request details |
| `review_code` | Get MR diff/changes for code review |
| `comment_on_mr` | Add a note to a merge request |
| `list_pipelines` | List pipelines (filter by ref) |
| `get_pipeline` | Get pipeline details |
| `retry_pipeline` | Retry a failed pipeline |
| `cancel_pipeline` | Cancel a running pipeline |
| `create_branch` | Create a new branch from a ref |
| `delete_branch` | Delete a branch |
| `list_branches` | List repository branches |
| `get_branch` | Get branch details |
| `push_files` | Create/update/delete/move files in a single commit |
| `get_file` | Read a file from the repository |
## Running Tests
```bash
python -m pytest tests -v
```
## Project Structure
```
gitlabmcp/
├── pyproject.toml
├── .env.example
├── client.py # Example MCP client
├── src/
│ └── gitlab_mcp_server/
│ ├── __init__.py
│ ├── __main__.py
│ ├── gitlab_client.py # GitLab API wrapper
│ ├── tools.py # MCP tool definitions + dispatch
│ └── server.py # MCP server (stdio transport)
└── tests/
├── conftest.py # Fixtures and mocks
├── test_gitlab_client.py
├── test_tools.py
└── test_server.py
```
