# GitLab MCP Server

An MCP (Model Context Protocol) server that allows LLMs to interact with GitLab. Access issues, merge requests, pipelines, and repository files directly from Claude Code or other MCP-compatible clients.

## Features

- Browse and search projects
- View issues and merge requests (including your own and team-labeled)
- Read MR diffs and comments
- Check pipeline status and job logs
- Browse repository files

## Setup

### 1. Install dependencies

```bash
make install
# or
uv sync
```

### 2. Create GitLab Personal Access Token

1. Go to GitLab → **Avatar** (top-right) → **Edit profile**
2. Left sidebar → **Access Tokens**
3. Click **Add new token**
4. Configure:
   - **Token name**: e.g., "MCP Server"
   - **Expiration date**: choose as needed
   - **Scopes**:
     - `read_api` (required)
     - `read_repository` (for file content access)
5. Click **Create personal access token**
6. **Copy the token** (won't be shown again)

**Direct URL**: `https://gitlab.com/-/user_settings/personal_access_tokens`

### 3. Configure environment

```bash
cp .env.example .env
```

Edit `.env` with your values:

```env
GITLAB_URL=https://gitlab.com
GITLAB_TOKEN=your-private-token-here
DEFAULT_ASSIGNEE=me
```

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| `GITLAB_URL` | Your GitLab instance URL | `https://gitlab.com` |
| `GITLAB_TOKEN` | Personal access token | (required) |
| `DEFAULT_ASSIGNEE` | Username for "my_*" tools filters | `me` |

## Usage

### Run directly

```bash
uv run python main.py
```

### Run in background

```bash
make start    # Start server
make stop     # Stop server
make restart  # Restart server
make status   # Check if running
make logs     # Tail server logs
```

### Add to Claude Code

Create `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "uv",
      "args": ["run", "python", "main.py"],
      "cwd": "/path/to/gitlab-mcp-server"
    }
  }
}
```

Or use the CLI:

```bash
claude mcp add gitlab -- uv run python main.py
```

Verify with `/mcp` command inside Claude Code.

### Test the server

```bash
# Test with MCP Inspector
npx @modelcontextprotocol/inspector uv run python main.py

# Test API connection
uv run python -c "
from tools.projects import get_client
with get_client() as client:
    r = client.get('/user')
    print('Authenticated as:', r.json().get('username'))
"
```

## Available Tools

### Projects

| Tool | Description |
|------|-------------|
| `list_projects` | List accessible projects (search, filter by ownership/membership) |
| `get_project` | Get project details by path |

### Issues

| Tool | Description |
|------|-------------|
| `list_issues` | List issues in a project (filter by state, labels, search) |
| `my_issues` | List issues assigned to you (uses `DEFAULT_ASSIGNEE`) |
| `team_issues` | List issues with a team label (default: "RE") |
| `get_issue` | Get issue details including description |
| `get_issue_comments` | Get comments/notes on an issue |

### Merge Requests

| Tool | Description |
|------|-------------|
| `list_merge_requests` | List MRs in a project (filter by state, branches, search) |
| `my_merge_requests` | List MRs assigned to you |
| `my_merge_requests_to_review` | List MRs where you are a reviewer |
| `team_merge_requests` | List MRs with a team label (default: "RE") |
| `get_merge_request` | Get MR details including description |
| `get_merge_request_changes` | Get MR file diffs |
| `get_merge_request_comments` | Get MR comments/discussions |

### Pipelines

| Tool | Description |
|------|-------------|
| `list_pipelines` | List pipelines in a project (filter by status, branch) |
| `get_pipeline_jobs` | Get jobs for a pipeline |
| `get_job_log` | Get job log output |

### Repository

| Tool | Description |
|------|-------------|
| `list_repository_tree` | List files/directories in a repo |
| `get_file_content` | Get file content from a repo |

## Project Structure

```
gitlab-mcp-server/
├── main.py           # Entry point
├── client.py         # HTTP client & settings
├── models.py         # Pydantic models
├── tools/
│   ├── projects.py   # Project tools
│   ├── issues.py     # Issue tools
│   ├── merge_requests.py  # MR tools
│   ├── pipelines.py  # Pipeline tools
│   └── repository.py # Repository tools
├── .env.example      # Environment template
└── Makefile          # Run commands
```

## License

MIT