ryan-rbw/kepler-mcp-gitlab-server

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:

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

# 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

Step 3: Deploy the Server

Option A: Direct Python

# 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

# 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

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

# 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

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

Development

Setup

# 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

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

# Check if server is running
curl http://localhost:8000/health

# Check logs
docker logs kepler-mcp-gitlab

GitLab API errors

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

License

MIT License - See for details.