# GitLab MCP Server

MCP server for GitLab REST API v4 built with `fastmcp`. Optimized for minimal token usage.

## Prerequisites

**For end users (Claude/Codex):**
- ✅ Python 3.10+ installed on your system
- ✅ GitLab Personal Access Token

**That's it!** No manual installation needed - everything else is automatic.

## How It Works

When you run the server through `npx`, the Node.js launcher **automatically**:

1. ✅ **Checks for Python** - Looks for `python3` or `python` in your PATH
2. ✅ **Creates virtual environment** - In `~/.cache/gitlab-mcp-server/venv`
3. ✅ **Installs dependencies** - `fastmcp` from `requirements.txt`
4. ✅ **Caches everything** - Fast subsequent launches

**First run**: ~10-30 seconds (one-time setup)
**Next runs**: Instant (uses cached venv)

### If Python is Not Found

If Python 3.10+ is not installed, the launcher will show instructions for your OS:

- **macOS**: `brew install python@3.11` or download from python.org
- **Linux**: `sudo apt install python3` or `sudo yum install python3`
- **Windows**: Download from python.org or `winget install Python.Python.3.11`

**You don't need to manually install `fastmcp` or create virtualenv!** The launcher handles that.

## Configuration

### Claude Code

Add the server using the CLI:

```bash
claude mcp add gitlab --transport stdio \
  --env GITLAB_TOKEN=your-gitlab-token \
  --env GITLAB_URL=https://gitlab.com \
  --env GITLAB_TIMEOUT=30 \
  -- npx -y git+https://github.com/YOUR_ORG/YOUR_REPO.git#main
```

Or add to `~/.claude.json`:

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "git+https://github.com/YOUR_ORG/YOUR_REPO.git#main"],
      "env": {
        "GITLAB_TOKEN": "your-gitlab-token",
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_TIMEOUT": "30"
      }
    }
  }
}
```

### Codex

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.gitlab]
command = "npx"
args = ["-y", "git+https://github.com/YOUR_ORG/YOUR_REPO.git#main"]
startup_timeout_sec = 60
enabled = true

[mcp_servers.gitlab.env]
GITLAB_TOKEN = "your-gitlab-token"
GITLAB_URL = "https://gitlab.com"
GITLAB_TIMEOUT = "30"
MCP_TRANSPORT = "stdio"
```

**Note:** Replace `YOUR_ORG/YOUR_REPO` with your GitHub repository path (e.g., `myorg/gitlab-mcp-server`).

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `GITLAB_TOKEN` | Yes | - | GitLab Personal Access Token |
| `GITLAB_URL` | No | `https://gitlab.com` | GitLab instance URL |
| `GITLAB_TIMEOUT` | No | `30` | API timeout in seconds |
| `MCP_TRANSPORT` | No | `stdio` | Transport protocol |
| `GITLAB_MCP_CACHE_DIR` | No | `~/.cache` | Custom cache directory for virtualenv |

## Available Tools

This server exposes 20+ GitLab operations as MCP tools:

### User
- **`gitlab_whoami`** - Get current user profile and validate credentials

### Projects
- **`gitlab_list_projects`** - List GitLab projects (supports search, pagination)
- **`gitlab_get_project`** - Get single project details by ID or path

### Branches
- **`gitlab_list_branches`** - List repository branches in a project

### Merge Requests
- **`gitlab_list_merge_requests`** - List merge requests (filter by state: opened, merged, closed)
- **`gitlab_get_merge_request`** - Get single merge request details
- **`gitlab_create_merge_request`** - Create new merge request
- **`gitlab_merge_merge_request`** - Merge a merge request
- **`gitlab_list_merge_request_notes`** - List comments on a merge request
- **`gitlab_create_merge_request_note`** - Add comment to a merge request
- **`gitlab_list_merge_request_discussions`** - List discussion threads on a merge request
- **`gitlab_create_merge_request_discussion_note`** - Reply to a discussion thread

### Issues
- **`gitlab_list_issues`** - List issues in a project (filter by state: opened, closed)
- **`gitlab_create_issue`** - Create new issue
- **`gitlab_list_issue_notes`** - List comments on an issue
- **`gitlab_create_issue_note`** - Add comment to an issue

### Pipelines & CI/CD
- **`gitlab_list_pipelines`** - List CI/CD pipelines (filter by ref, status)
- **`gitlab_get_pipeline`** - Get single pipeline details
- **`gitlab_create_pipeline`** - Trigger new pipeline
- **`gitlab_list_pipeline_jobs`** - List jobs in a pipeline
- **`gitlab_get_job`** - Get single job details
- **`gitlab_play_job`** - Start a manual job
- **`gitlab_retry_job`** - Retry a failed job
- **`gitlab_cancel_job`** - Cancel a running/pending job

All tools support GitLab.com and self-hosted GitLab instances via the `GITLAB_URL` environment variable.

## For Developers

If you're developing or testing locally:

```bash
# Clone the repo
git clone https://github.com/YOUR_ORG/YOUR_REPO.git
cd YOUR_REPO

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export GITLAB_TOKEN='your-gitlab-token'
export GITLAB_URL='https://gitlab.com'

# Run the server directly
python3 gitlab_mcp_server.py

# Or test via Node.js launcher
node bin/gitlab-mcp-server.js
```

**Note for end users**: You don't need to do this! The npx launcher handles everything automatically.