Kepler MCP GitLab Server

开普勒MCP GitLab服务器

一个生产就绪的MCP（模型上下文协议）服务器，为Claude Desktop和ChatGPT等AI助手提供GitLab集成工具。

运作原理

此MCP服务器充当AI助手（ChatGPT、Claude等）和GitLab实例之间的桥梁。用户通过GitLab OAuth进行身份验证，就像连接任何第三方应用程序一样。

┌─────────────────┐      ┌─────────────────────┐      ┌─────────────────┐
│   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  │
        │                         │   ◄────────────────────► │

面向终端用户：只需将MCP服务器URL添加到他们的AI助手中，并使用GitLab进行授权。无需令牌或配置。

对于管理员：一次性设置部署服务器并向GitLab注册OAuth应用程序。

特性

• GitLab集成：通过MCP工具访问项目、问题、合并请求等
• OAuth 2.0身份验证：用户通过GitLab授权-无需管理令牌
• 每个用户权限：尊重每个用户的GitLab权限
• 多种运输方式：stdio用于本地（Claude Desktop），SSE用于HTTP（ChatGPT）
• 安全令牌存储：使用Fernet加密的加密会话存储
• Docker支持：生产就绪的容器图像

可用工具

连接后，用户可以要求他们的AI助手：

______________________________________________________________________

部署指南（适用于管理员）

本节适用于为其组织部署MCP服务器的IT管理员。

先决条件

• Python 3.12+或Docker
• 访问您的GitLab实例（管理员或创建OAuth应用程序的能力）
• 运行MCP服务器的服务器/主机（可以与GitLab相同或单独）

了解OAuth应用程序凭据

部署此服务器时，需要在GitLab中将其注册为OAuth应用程序。这类似于Slack、GitHub或任何第三方集成的工作原理。

为什么？ GitLab需要知道：

1. 谁在问 （客户端ID）-标识您的MCP服务器
2. 真的是你 （客户端机密）-证明请求是合法的
3. 将用户送回何处 （重定向URI）-授权后

这些是 应用程序凭据，而不是用户凭据。您只需设置一次，组织中的所有用户就可以连接，而无需任何其他配置。

┌─────────────────────────────────────────────────────────────────────┐
│                    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!                 │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

步骤1：在GitLab中注册OAuth应用程序

1. 以管理员身份（或用户级应用程序的任何用户）登录您的GitLab实例

1. 导航到：

- 实例范围内 （推荐）：行政区→ 应用程序 - 用户级别：用户设置→ 应用程序

1. 点击 新应用程序 并填写：

1. 点击 保存应用程序

1. 复制并安全存储:

- 应用标识符 （客户端ID） - 秘密 （客户端密码）-仅显示一次！

步骤2：配置服务器

创建配置文件或设置环境变量：

选项A：环境变量

# 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

选项B： .env 文件

创建一个 .env 项目根目录中具有相同变量的文件（没有 export).

GitLab.com与自托管

步骤3：部署服务器

选项A：直接使用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

选项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

选项C:Docker编写

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

步骤4：验证部署

# 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

第五步：通知用户

部署后，与用户分享以下说明：

从ChatGPT连接到GitLab 1. 在ChatGPT中，转到设置→ 连接→ 添加MCP服务器 1. 输入服务器URL: https://your-mcp-server.com/sse 1. 点击连接-您将被重定向到GitLab 1. 登录GitLab并点击“授权” 1. 完成！您现在可以向ChatGPT询问您的GitLab项目。 尝试：“列出我的GitLab项目”或“显示项目X中的未解决问题”

______________________________________________________________________

配置参考

所有环境变量

\*需要时 OAUTH_USER_AUTH_ENABLED=true \*\*如果需要持续会话，则需要一起使用

______________________________________________________________________

发展

设置

# Clone and setup
git clone 
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]"

质量检查

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

项目结构

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)

______________________________________________________________________

安全

• OAuth 2.0与PKCE：行业标准安全身份验证
• 没有存储密码：用户直接通过GitLab进行身份验证
• 每个用户权限：尊重每个用户的GitLab访问权限
• 加密令牌：使用Fernet静态加密的会话令牌
• 秘密编辑：敏感值从不出现在日志中
• 非根容器：Docker镜像以无特权用户身份运行

______________________________________________________________________

故障排除

OAuth错误

“重定向URI无效”

• 确保GitLab中的重定向URI与服务器的回调URL完全匹配
• 检查尾随斜线，http与https

“无效客户端”

• 验证客户端ID是否正确
• 检查OAuth应用程序是否仍在GitLab中处于活动状态

“无效状态”

• 状态已过期（默认10分钟）-重试该流程
• 服务器可能在OAuth流期间重新启动

连接问题

健康检查失败

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

# Check logs
docker logs kepler-mcp-gitlab

GitLab API错误

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

______________________________________________________________________

许可证

MIT许可证-请参阅 许可证 了解详情。