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
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:
Who is asking (Client ID) - Identifies your MCP server
That it's really you (Client Secret) - Proves the request is legitimate
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
Log into your GitLab instance as an admin (or any user for user-level apps)
Navigate to:
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 |
Click Save application
Copy and securely store:
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
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
# 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
In ChatGPT, go to Settings → Connections → Add MCP Server
Enter the server URL: https://your-mcp-server.com/sse
Click Connect - you'll be redirected to GitLab
Log in to GitLab and click "Authorize"
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
# 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"
"Invalid state"
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 LICENSE for details.
