# Kepler MCP GitLab Server

A production-ready MCP (Model Context Protocol) server providing GitLab integration tools for AI assistants like Claude Desktop and ChatGPT.

## How It Works

This MCP server acts as a bridge between AI assistants (ChatGPT, Claude, etc.) and your GitLab instance. Users authenticate via GitLab OAuth - just like connecting any third-party app.

```
┌─────────────────┐      ┌─────────────────────┐      ┌─────────────────┐
│   AI Assistant  │      │   MCP Server        │      │    GitLab       │
│   (ChatGPT,     │◄────►│   (Your Company     │◄────►│    (Your        │
│    Claude)      │      │    Hosted)          │      │    Instance)    │
└─────────────────┘      └─────────────────────┘      └─────────────────┘
        │                         │                          │
        │    1. User connects     │                          │
        │    ─────────────────►   │                          │
        │                         │   2. Redirect to GitLab  │
        │                         │   ─────────────────────► │
        │                         │                          │
        │                         │   3. User authorizes     │
        │                         │   ◄───────────────────── │
        │                         │                          │
        │    4. Connected!        │   5. API calls with      │
        │    ◄─────────────────   │      user's permissions  │
        │                         │   ◄────────────────────► │
```

**For end users**: Simply add the MCP server URL to their AI assistant and authorize with GitLab. No tokens or configuration needed.

**For administrators**: One-time setup to deploy the server and register the OAuth application with GitLab.

## Features

- **GitLab Integration**: Access projects, issues, merge requests, and more through MCP tools
- **OAuth 2.0 Authentication**: Users authorize via GitLab - no tokens to manage
- **Per-User Permissions**: Each user's GitLab permissions are respected
- **Multiple Transport Modes**: stdio for local (Claude Desktop), SSE for HTTP (ChatGPT)
- **Secure Token Storage**: Encrypted session storage using Fernet encryption
- **Docker Support**: Production-ready container images

## Available Tools

Once connected, users can ask their AI assistant to:

| Tool | Description |
|------|-------------|
| **Projects** | |
| `list_projects` | List accessible GitLab projects |
| `get_project` | Get project details |
| `search_projects` | Search for projects |
| `get_project_languages` | Get language breakdown |
| **Issues** | |
| `list_issues` | List issues in a project |
| `get_issue` | Get issue details |
| `create_issue` | Create a new issue |
| `update_issue` | Update an issue |
| `close_issue` / `reopen_issue` | Change issue state |
| `list_issue_comments` | List comments on an issue |
| `add_issue_comment` | Add a comment |
| **Merge Requests** | |
| `list_merge_requests` | List MRs in a project |
| `get_merge_request` | Get MR details |
| `create_merge_request` | Create a new MR |
| `update_merge_request` | Update an MR |
| `merge_merge_request` | Merge an MR |
| `approve_merge_request` | Approve an MR |
| `get_merge_request_changes` | Get MR diff |
| `list_merge_request_discussions` | List review threads |
| **Repository** | |
| `list_branches` | List repository branches |
| `get_branch` | Get branch details |
| `create_branch` | Create a new branch |
| `delete_branch` | Delete a branch |
| `list_tags` | List repository tags |
| `get_tag` | Get tag details |
| `create_tag` | Create a new tag |
| `delete_tag` | Delete a tag |
| `compare_branches` | Compare two branches/commits |
| `list_repository_tree` | List files and directories |
| `get_file` | Get file metadata |
| `get_file_content` | Get file contents (decoded) |
| `create_file` | Create a new file |
| `update_file` | Update an existing file |
| `delete_file` | Delete a file |
| `get_file_blame` | Get file blame/history |
| `list_commits` | List repository commits |
| `get_commit` | Get commit details |
| `get_commit_diff` | Get commit diff |
| `cherry_pick_commit` | Cherry-pick a commit |
| `get_commit_refs` | Get refs containing a commit |
| **Utilities** | |
| `get_current_user` | Get authenticated user info |
| `get_gitlab_config` | Get server configuration |

---

# Deployment Guide (For Administrators)

This section is for IT administrators deploying the MCP server for their organization.

## Prerequisites

- Python 3.12+ or Docker
- Access to your GitLab instance (admin or ability to create OAuth applications)
- A server/host to run the MCP server (can be the same as GitLab or separate)

## Understanding OAuth Application Credentials

When you deploy this server, you need to register it as an OAuth application with GitLab. This is similar to how Slack, GitHub, or any third-party integration works.

**Why?** GitLab needs to know:
1. **Who is asking** (Client ID) - Identifies your MCP server
2. **That it's really you** (Client Secret) - Proves the request is legitimate
3. **Where to send users back** (Redirect URI) - After they authorize

These are **application credentials**, not user credentials. You set them up once, and then all users in your organization can connect without any additional configuration.

```
┌─────────────────────────────────────────────────────────────────────┐
│                    OAuth Flow Explained                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  1. User clicks "Connect to GitLab" in ChatGPT                      │
│                          │                                           │
│                          ▼                                           │
│  2. MCP Server redirects to GitLab:                                 │
│     gitlab.com/oauth/authorize?client_id=ABC123&...                 │
│                          │                                           │
│                          │  ◄── GitLab checks: "Is ABC123 a valid   │
│                          │       registered application?"            │
│                          ▼                                           │
│  3. User sees GitLab login page, then:                              │
│     "Kepler MCP Server wants to access your account"                │
│     [Authorize] [Deny]                                              │
│                          │                                           │
│                          ▼                                           │
│  4. User clicks Authorize, GitLab redirects back with temp code     │
│                          │                                           │
│                          ▼                                           │
│  5. MCP Server exchanges code for tokens:                           │
│     POST gitlab.com/oauth/token                                     │
│     { client_id: ABC123, client_secret: XYZ789, code: ... }         │
│                          │                                           │
│                          │  ◄── GitLab verifies the secret matches  │
│                          │       the registered application          │
│                          ▼                                           │
│  6. GitLab returns access token, user is connected!                 │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘
```

## Step 1: Register OAuth Application in GitLab

1. Log into your GitLab instance as an admin (or any user for user-level apps)

2. Navigate to:
   - **Instance-wide** (recommended): Admin Area → Applications
   - **User-level**: User Settings → Applications

3. Click **New Application** and fill in:

   | Field | Value |
   |-------|-------|
   | **Name** | `Kepler MCP GitLab Server` |
   | **Redirect URI** | `https://your-mcp-server.com/oauth/callback` |
   | **Confidential** | ✅ Yes (checked) |
   | **Scopes** | ✅ `api` ✅ `read_user` ✅ `read_repository` |

4. Click **Save application**

5. **Copy and securely store**:
   - **Application ID** (Client ID)
   - **Secret** (Client Secret) - shown only once!

## Step 2: Configure the Server

Create a configuration file or set environment variables:

### Option A: Environment Variables

```bash
# Required: GitLab Instance
export KEPLER_MCP_GITLAB_URL=https://gitlab.your-company.com

# Required: OAuth Application Credentials (from Step 1)
export KEPLER_MCP_OAUTH_USER_AUTH_ENABLED=true
export KEPLER_MCP_OAUTH_CLIENT_ID=your_application_id_here
export KEPLER_MCP_OAUTH_CLIENT_SECRET=your_secret_here
export KEPLER_MCP_OAUTH_REDIRECT_URI=https://your-mcp-server.com/oauth/callback
export KEPLER_MCP_OAUTH_SCOPE="api read_user read_repository"

# Required: OAuth Endpoints (adjust domain for your GitLab)
export KEPLER_MCP_OAUTH_AUTHORIZATION_URL=https://gitlab.your-company.com/oauth/authorize
export KEPLER_MCP_OAUTH_TOKEN_URL=https://gitlab.your-company.com/oauth/token
export KEPLER_MCP_OAUTH_USERINFO_URL=https://gitlab.your-company.com/api/v4/user

# Server Settings
export KEPLER_MCP_TRANSPORT_MODE=sse
export KEPLER_MCP_HOST=0.0.0.0
export KEPLER_MCP_PORT=8000

# Optional: Token Encryption (recommended for production)
# Generate key: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
export KEPLER_MCP_TOKEN_ENCRYPTION_KEY=your_generated_fernet_key
export KEPLER_MCP_TOKEN_STORE_PATH=/var/lib/kepler-mcp/tokens.json
```

### Option B: `.env` File

Create a `.env` file in the project root with the same variables (without `export`).

### GitLab.com vs Self-Hosted

| Setting | GitLab.com | Self-Hosted |
|---------|-----------|-------------|
| `GITLAB_URL` | `https://gitlab.com` | `https://gitlab.your-company.com` |
| `OAUTH_AUTHORIZATION_URL` | `https://gitlab.com/oauth/authorize` | `https://gitlab.your-company.com/oauth/authorize` |
| `OAUTH_TOKEN_URL` | `https://gitlab.com/oauth/token` | `https://gitlab.your-company.com/oauth/token` |
| `OAUTH_USERINFO_URL` | `https://gitlab.com/api/v4/user` | `https://gitlab.your-company.com/api/v4/user` |

## Step 3: Deploy the Server

### Option A: Direct Python

```bash
# Create virtual environment
python3.12 -m venv .venv
source .venv/bin/activate

# Install
pip install -e .

# Run
python -m kepler_mcp_gitlab.cli serve --transport sse
```

### Option B: Docker

```bash
# Build
docker build -t kepler-mcp-gitlab -f docker/Dockerfile .

# Run
docker run -d \
  --name kepler-mcp-gitlab \
  -p 8000:8000 \
  -e KEPLER_MCP_GITLAB_URL=https://gitlab.your-company.com \
  -e KEPLER_MCP_OAUTH_USER_AUTH_ENABLED=true \
  -e KEPLER_MCP_OAUTH_CLIENT_ID=your_client_id \
  -e KEPLER_MCP_OAUTH_CLIENT_SECRET=your_secret \
  -e KEPLER_MCP_OAUTH_REDIRECT_URI=https://your-mcp-server.com/oauth/callback \
  -e KEPLER_MCP_OAUTH_AUTHORIZATION_URL=https://gitlab.your-company.com/oauth/authorize \
  -e KEPLER_MCP_OAUTH_TOKEN_URL=https://gitlab.your-company.com/oauth/token \
  -e KEPLER_MCP_OAUTH_SCOPE="api read_user read_repository" \
  kepler-mcp-gitlab
```

### Option C: Docker Compose

```yaml
version: '3.8'
services:
  mcp-gitlab:
    build:
      context: .
      dockerfile: docker/Dockerfile
    ports:
      - "8000:8000"
    environment:
      KEPLER_MCP_GITLAB_URL: https://gitlab.your-company.com
      KEPLER_MCP_OAUTH_USER_AUTH_ENABLED: "true"
      KEPLER_MCP_OAUTH_CLIENT_ID: ${OAUTH_CLIENT_ID}
      KEPLER_MCP_OAUTH_CLIENT_SECRET: ${OAUTH_CLIENT_SECRET}
      KEPLER_MCP_OAUTH_REDIRECT_URI: https://your-mcp-server.com/oauth/callback
      KEPLER_MCP_OAUTH_AUTHORIZATION_URL: https://gitlab.your-company.com/oauth/authorize
      KEPLER_MCP_OAUTH_TOKEN_URL: https://gitlab.your-company.com/oauth/token
      KEPLER_MCP_OAUTH_SCOPE: "api read_user read_repository"
    restart: unless-stopped
```

## Step 4: Verify Deployment

```bash
# Health check
curl https://your-mcp-server.com/health

# Expected response:
# {"status": "ok", "app_name": "Kepler MCP GitLab Server", "environment": "prod"}

# Test OAuth redirect (should redirect to GitLab)
curl -I https://your-mcp-server.com/oauth/authorize

# Expected: HTTP 302 with Location header pointing to GitLab
```

## Step 5: Inform Your Users

Once deployed, share these instructions with your users:

> **Connecting to GitLab from ChatGPT**
>
> 1. In ChatGPT, go to Settings → Connections → Add MCP Server
> 2. Enter the server URL: `https://your-mcp-server.com/sse`
> 3. Click Connect - you'll be redirected to GitLab
> 4. Log in to GitLab and click "Authorize"
> 5. Done! You can now ask ChatGPT about your GitLab projects.
>
> Try: "List my GitLab projects" or "Show open issues in project X"

---

# Configuration Reference

## All Environment Variables

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| **Core** | | | |
| `KEPLER_MCP_APP_NAME` | Application name | `Kepler MCP GitLab Server` | No |
| `KEPLER_MCP_LOG_LEVEL` | Log level | `INFO` | No |
| `KEPLER_MCP_ENVIRONMENT` | Environment (local/dev/stage/prod) | `local` | No |
| `KEPLER_MCP_TRANSPORT_MODE` | Transport (stdio/sse) | `stdio` | No |
| `KEPLER_MCP_HOST` | Server bind host | `0.0.0.0` | No |
| `KEPLER_MCP_PORT` | Server bind port | `8000` | No |
| **GitLab** | | | |
| `KEPLER_MCP_GITLAB_URL` | GitLab instance URL | `https://gitlab.com` | Yes |
| **OAuth** (required for SSE mode) | | | |
| `KEPLER_MCP_OAUTH_USER_AUTH_ENABLED` | Enable OAuth | `false` | Yes* |
| `KEPLER_MCP_OAUTH_CLIENT_ID` | OAuth Client ID | - | Yes* |
| `KEPLER_MCP_OAUTH_CLIENT_SECRET` | OAuth Client Secret | - | Yes* |
| `KEPLER_MCP_OAUTH_AUTHORIZATION_URL` | OAuth authorize endpoint | - | Yes* |
| `KEPLER_MCP_OAUTH_TOKEN_URL` | OAuth token endpoint | - | Yes* |
| `KEPLER_MCP_OAUTH_REDIRECT_URI` | OAuth callback URL | - | Yes* |
| `KEPLER_MCP_OAUTH_SCOPE` | OAuth scopes | - | Yes* |
| `KEPLER_MCP_OAUTH_USERINFO_URL` | User info endpoint | - | No |
| **Token Storage** | | | |
| `KEPLER_MCP_TOKEN_ENCRYPTION_KEY` | Fernet key for encryption | - | No** |
| `KEPLER_MCP_TOKEN_STORE_PATH` | Path for token persistence | - | No** |
| **Rate Limiting** | | | |
| `KEPLER_MCP_RATE_LIMIT_REQUESTS_PER_MINUTE` | Max requests/min | `60` | No |
| `KEPLER_MCP_RATE_LIMIT_BURST` | Burst size | `10` | No |

\* Required when `OAUTH_USER_AUTH_ENABLED=true`
\** Required together if persistent sessions are needed

---

# Development

## Setup

```bash
# Clone and setup
git clone <repo>
cd kepler-mcp-gitlab-server

# Create virtual environment
python3.12 -m venv .venv
source .venv/bin/activate

# Install with dev dependencies
pip install -e ".[dev]"
```

## Quality Checks

```bash
make lint        # Ruff linting
make typecheck   # Mypy type checking
make test        # Run tests
make coverage    # Tests with coverage report
make check-all   # All checks
```

## Project Structure

```
src/kepler_mcp_gitlab/
├── cli.py              # Command-line interface
├── server.py           # FastMCP server setup
├── config.py           # Configuration management
├── context.py          # Request context and session management
├── application.py      # Tool registration
├── transport.py        # stdio/SSE transport handlers
├── security.py         # Auth strategies, token handling
├── gitlab/
│   ├── client.py       # GitLab API client
│   └── exceptions.py   # GitLab-specific errors
├── oauth/
│   ├── flows.py        # OAuth flow implementations
│   ├── pkce.py         # PKCE support
│   ├── session.py      # Session management
│   └── token_store.py  # Token persistence
└── tools/
    ├── projects.py     # Project tools
    ├── issues.py       # Issue tools
    ├── merge_requests.py # MR tools
    └── repository.py   # Repository tools (branches, tags, files, commits)
```

---

# Security

- **OAuth 2.0 with PKCE**: Industry-standard secure authentication
- **No stored passwords**: Users authenticate directly with GitLab
- **Per-user permissions**: Each user's GitLab access rights are respected
- **Encrypted tokens**: Session tokens encrypted at rest with Fernet
- **Secret redaction**: Sensitive values never appear in logs
- **Non-root containers**: Docker images run as unprivileged user

---

# Troubleshooting

## OAuth Errors

**"Invalid redirect URI"**
- Ensure the redirect URI in GitLab exactly matches your server's callback URL
- Check for trailing slashes, http vs https

**"Invalid client"**
- Verify Client ID is correct
- Check if the OAuth application is still active in GitLab

**"Invalid state"**
- State expired (default 10 min) - try the flow again
- Server may have restarted during the OAuth flow

## Connection Issues

**Health check fails**
```bash
# Check if server is running
curl http://localhost:8000/health

# Check logs
docker logs kepler-mcp-gitlab
```

**GitLab API errors**
```bash
# Test GitLab connectivity directly
curl -H "Authorization: Bearer <token>" https://gitlab.your-company.com/api/v4/user
```

---

# License

MIT License - See [LICENSE](LICENSE) for details.