# 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
```