CERN GitLab MCP Server

CERN GitLab MCP Server

An MCP server that connects LLMs to CERN GitLab for discovering HEP code, documentation, and analysis examples.

特性

• 14个MCP工具 用于搜索、浏览和分析CERN GitLab存储库
• 双模式操作 --stdio（单用户）和HTTP（多用户）模式
• CLI工具 (cerngitlab-cli)用于直接命令行使用
• 公众知情权 --适用于公共存储库，无需身份验证
• 多用户HTTP模式 --CERN SSO+GitLab OAuth认证，用于集中部署；GitLab以本机方式强制执行所有访问权限
• 专注于HEP --Python和C++生态系统的依赖解析，二进制检测 .root 文件，问题搜索
• 健壮 --速率限制、指数回退重试、优雅的错误处理

安装

需要Python 3.10+。

快速入门（推荐）

无需安装，只需使用 uvx 直接运行：

uvx cerngitlab-mcp

来自PyPI

pip install cerngitlab-mcp

来源

git clone https://github.com/MohamedElashri/cerngitlab-mcp
cd cerngitlab-mcp
uv sync

配置

所有设置都是通过前缀为的环境变量配置的 CERNGITLAB_:

认证

服务器以两种模式工作：

• 无令牌 --访问所有公共存储库。足够用于大多数HEP代码发现。
• 带令牌 --对内部/私人项目、代码搜索和维基页面的额外访问。

要创建令牌，请执行以下操作：

1. 首选https://gitlab.cern.ch/-/user_settings/personal_access_tokens
2. 使用创建令牌 read_api 范围
3. 集 CERNGITLAB_TOKEN=glpat-xxxxxxxxxxxx

注： 代码搜索(search_code)，问题搜索(search_issues)，和wiki(get_wiki_pages)这些工具需要在CERN GitLab上进行身份验证。

用法

克劳德桌面版

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "cerngitlab": {
      "command": "uvx",
      "args": ["cerngitlab-mcp"],
      "env": {
        "CERNGITLAB_TOKEN": "glpat-xxxxxxxxxxxx"
      }
    }
  }
}

macOS用户注意事项： 如果您看到以下错误 uvx 如果找不到，您可能需要提供绝对路径。Claude Desktop不支持 ~ 或 $HOME 扩张。 1. 跑 which uvx 在您的终端中查找路径（例如。， /Users/yourusername/.local/bin/uvx). 1. 在中使用该绝对路径 command 字段： ``json "command": "/Users/yourusername/.local/bin/uvx" ``

克劳德代码

项目特定（默认） --安装在当前目录的配置中：

claude mcp add cerngitlab-mcp -- uvx cerngitlab-mcp

全球的 --为您的用户帐户安装（适用于所有项目）：

claude mcp add --scope user cerngitlab-mcp -- uvx cerngitlab-mcp

要包含身份验证，请添加 -e CERNGITLAB_TOKEN=glpat-xxxxxxxxxxxx 之前 --:

# Example: Global installation with token
claude mcp add --scope user -e CERNGITLAB_TOKEN=glpat-xxxxxxxxxxxx cerngitlab-mcp -- uvx cerngitlab-mcp

手动配置 --您还可以在以下位置手动编辑全局配置 ~/.claude.json （在Linux/macOS上）或 %APPDATA%\Claude\claude.json （在Windows上）：

{
  "mcpServers": {
    "cerngitlab": {
      "command": "uvx",
      "args": ["cerngitlab-mcp"],
      "env": {
        "CERNGITLAB_TOKEN": "glpat-xxxxxxxxxxxx"
      }
    }
  }
}

GitHub Copilot

添加到您的VS代码 settings.json:

{
  "mcp": {
    "servers": {
      "cerngitlab": {
        "command": "uvx",
        "args": ["cerngitlab-mcp"],
        "env": {
          "CERNGITLAB_TOKEN": "glpat-xxxxxxxxxxxx"
        }
      }
    }
  }
}

或者添加一个 .vscode/mcp.json 对于您的项目：

{
  "servers": {
    "cerngitlab": {
      "command": "uvx",
      "args": ["cerngitlab-mcp"],
      "env": {
        "CERNGITLAB_TOKEN": "glpat-xxxxxxxxxxxx"
      }
    }
  }
}

Gemini CLI

添加到您的 ~/.gemini/settings.json:

{
  "mcpServers": {
    "cerngitlab": {
      "command": "uvx",
      "args": ["cerngitlab-mcp"],
      "env": {
        "CERNGITLAB_TOKEN": "glpat-xxxxxxxxxxxx"
      }
    }
  }
}

直接使用

标准模式（单用户，默认）

# Run with uvx (no install needed)
uvx cerngitlab-mcp

# Or if installed from PyPI
cerngitlab-mcp

# Explicit stdio mode
cerngitlab-mcp --mode stdio

# Or from source
uv run cerngitlab-mcp

# With authentication
CERNGITLAB_TOKEN=glpat-xxx uvx cerngitlab-mcp

HTTP模式（多用户）

# HTTP mode for multi-user deployment
cerngitlab-mcp --mode http --host 0.0.0.0 --port 8080

# Or use environment variables
CERNGITLAB_HTTP_MODE=true CERNGITLAB_HOST=0.0.0.0 CERNGITLAB_PORT=8080 cerngitlab-mcp

# Dedicated HTTP entry point
cerngitlab-mcp-http

模式选择

• --mode stdio -使用stdin/stdout的单用户模式（默认）
• --mode http -使用HTTP API的多用户模式
• --mode auto -基于环境变量的自动检测

如果发生以下情况，服务器会自动检测HTTP模式 CERNGITLAB_HTTP_MODE, CERNGITLAB_HOST，或 CERNGITLAB_PORT 设置环境变量。

工具

有关详细的参数文档，请参阅 docs/dev.md.

示例提示

搜索存储库

“在CERN GitLab中搜索与ROOT分析相关的Python存储库，并向我展示最受欢迎的存储库”

了解一个项目

“在CERN GitLab上获取lhcb/Davici项目的README和文件结构”

查找合适的示例

“在CERN GitLab上搜索使用RooFit的存储库，并向我展示示例拟合代码”

查看LHCb软件堆栈代码

“在LHCb sim11堆栈中搜索Boole项目中的初始化例程”

分析项目结构

“检查lhcb/allen项目，了解其构建系统、依赖关系和CI管道配置”

查找使用上下文

“在atlas/athena项目中搜索与‘分段错误’相关的问题，看看其他人是否遇到过这种情况”

跟踪发布

“列出lhcb/Davici的最新版本，并向我展示最新版本的发行说明”

查找框架配置

“在CERN GitLab上搜索高迪框架配置文件，并向我展示示例”

发展

看 docs/dev.md 用于开发设置、项目结构、测试和发布说明。

多用户HTTP部署

HTTP模式为多个用户提供了一个集中式服务器。它使用 CERN SSO+GitLab OAuth 对于身份验证，用户使用其现有的CERN身份进行身份验证，GitLab自己的权限系统执行所有访问控制。

先决条件

1. CERN SSO客户端 --在以下网址注册客户 CERN授权服务。注意客户端ID。
2. GitLab OAuth应用程序 --创建一个 https://gitlab.cern.ch/-/profile/applications.

- 将重定向URI设置为 https://gitlabmcp.cern.ch/oauth/callback （替换为实际URL） - 启用 read_api read_repository read_user 范围 - 注意应用程序ID和密码。

设置

export CERNGITLAB_CERN_CLIENT_ID=your-cern-sso-client-id
export CERNGITLAB_GITLAB_OAUTH_CLIENT_ID=your-gitlab-oauth-app-id
export CERNGITLAB_GITLAB_OAUTH_CLIENT_SECRET=your-gitlab-oauth-secret
export CERNGITLAB_SERVER_BASE_URL=https://gitlabmcp.cern.ch
export CERNGITLAB_SESSION_STORAGE_PATH=/var/lib/cerngitlab/sessions  # optional

# Start the server
cerngitlab-mcp --mode http --host 0.0.0.0 --port 8000

看 examples/oauth_server.py 在自包含的参考脚本的存储库中。

身份验证流程

1. 客户端发送请求 Authorization: Bearer 头球
2. 服务器通过CERN的JWKS端点验证CERN SSO令牌。
3. 如果用户没有活动的GitLab OAuth会话，服务器将返回HTTP 202和 authorization_url 现场。
4. 用户访问该URL，授权GitLab OAuth应用程序，并被重定向回 /oauth/callback.
5. 后续请求使用存储的GitLab OAuth令牌提供服务。会话将在2小时后过期。

API终点

示例用法

假设服务器正在运行 https://gitlabmcp.cern.ch 和那个 CERN_SSO_TOKEN 环境变量设置为有效的CERN SSO令牌：

# Step 1 – check authorization status
curl -H "Authorization: Bearer $CERN_SSO_TOKEN" \
     https://gitlabmcp.cern.ch/oauth/authorize
# If 202, visit the returned authorization_url in a browser and authorize.

# Step 2 – list available tools (once authorized)
curl -H "Authorization: Bearer $CERN_SSO_TOKEN" \
     https://gitlabmcp.cern.ch/tools

# Step 3 – execute a tool
curl -X POST -H "Authorization: Bearer $CERN_SSO_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"arguments": {"query": "ROOT"}}' \
     https://gitlabmcp.cern.ch/tools/search_projects

# Revoke session
curl -X DELETE -H "Authorization: Bearer $CERN_SSO_TOKEN" \
     https://gitlabmcp.cern.ch/session

CLI工具

命令行界面也可直接使用，无需MCP服务器：

# Install or use with uvx
uvx cerngitlab-cli

# Test connectivity
cerngitlab-cli test-connection

# Search for projects
cerngitlab-cli search-projects --query "ROOT analysis" --language python

# Get project info
cerngitlab-cli get-project-info --project lhcb/DaVinci

# Search code
cerngitlab-cli search-code --search-term "RooFit" --per-page 10

# Inspect project structure
cerngitlab-cli inspect-project --project lhcb/allen

所有命令都将JSON输出到stdout，以便于管道和组合。看 cerngitlab-cli --help 查看完整的命令列表。

技能档案

详细的技能档案(SKILL.md)可用于：

• 所有14个工具的完整文档
• 输入/输出规格
• 使用示例
• 身份验证要求

LLM或代理可以使用它来了解可用的工具以及如何使用它们。

许可证

此软件根据AGPL-3.0许可证提供。