CERN GitLab MCP Server

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

Features

14 MCP tools for searching, browsing, and analyzing CERN GitLab repositories
Dual-mode operation — stdio (single-user) and HTTP (multi-user) modes
CLI tool (cerngitlab-cli) for direct command-line usage
Public access — works without authentication for public repositories
Multi-user support — HTTP mode enables centralized deployment for multiple users
HEP-focused — dependency parsing for Python and C++ ecosystems, binary detection for .root files, issue search
Robust — rate limiting, retries with exponential backoff, graceful error handling

Installation

Requires Python 3.10+.

Quickstart (recommended)

No installation needed — just use uvx to run directly:

uvx cerngitlab-mcp

From PyPI

pip install cerngitlab-mcp

From source

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

Configuration

All settings are configured via environment variables prefixed with CERNGITLAB_:

Variable	Default	Description
`CERNGITLAB_GITLAB_URL`	`https://gitlab.cern.ch`	GitLab instance URL
`CERNGITLAB_TOKEN`	(empty)	Personal access token (optional)
`CERNGITLAB_TIMEOUT`	`30`	HTTP timeout in seconds
`CERNGITLAB_MAX_RETRIES`	`3`	Max retries for failed requests
`CERNGITLAB_RATE_LIMIT_PER_MINUTE`	`300`	API rate limit
`CERNGITLAB_LOG_LEVEL`	`INFO`	Logging level
`CERNGITLAB_DEFAULT_REF`	(empty)	Default Git branch or tag to search within (e.g., `main`, `master`, `v1.2.0`). Empty means search all branches.
`CERNGITLAB_HTTP_MODE`	(empty)	Set to enable HTTP mode for multi-user deployment
`CERNGITLAB_HOST`	`localhost`	HTTP mode: host to bind to
`CERNGITLAB_PORT`	`8000`	HTTP mode: port to bind to

Authentication

The server works in two modes:

Without token — Access to all public repositories. Sufficient for most HEP code discovery.
With token — Additional access to internal/private projects, code search, and wiki pages.

To create a token:

Go to https://gitlab.cern.ch/-/user_settings/personal_access_tokens
Create a token with read_api scope
Set CERNGITLAB_TOKEN=glpat-xxxxxxxxxxxx

Note: The code search (search_code), issue search (search_issues), and wiki (get_wiki_pages) tools require authentication on CERN GitLab.

Usage

Claude Desktop

Add to your claude_desktop_config.json:

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

Note for macOS users: If you see an error about uvx not being found, you may need to provide the absolute path. Claude Desktop does not support ~ or $HOME expansion.

Run which uvx in your terminal to find the path (e.g., /Users/yourusername/.local/bin/uvx).

Use that absolute path in the command field:
"command": "/Users/yourusername/.local/bin/uvx"

Claude Code

Project-specific (default) — installs in the current directory's configuration:

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

Global — installs for your user account (works in all projects):

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

To include authentication, add -e CERNGITLAB_TOKEN=glpat-xxxxxxxxxxxx before the --:

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

Manual Configuration — you can also manually edit your global config at ~/.claude.json (on Linux/macOS) or %APPDATA%\Claude\claude.json (on Windows):

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

GitHub Copilot

Add to your VS Code settings.json:

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

Or add a .vscode/mcp.json to your project:

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

Gemini CLI

Add to your ~/.gemini/settings.json:

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

Direct usage

Stdio Mode (Single-User, Default)

# 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 Mode (Multi-User)

# 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 Selection

--mode stdio - Single-user mode using stdin/stdout (default)
--mode http - Multi-user mode using HTTP API
--mode auto - Auto-detect based on environment variables

The server automatically detects HTTP mode if CERNGITLAB_HTTP_MODE, CERNGITLAB_HOST, or CERNGITLAB_PORT environment variables are set.

Tools

Tool	Description	Auth required
`search_projects`	Search for public CERN GitLab projects (repositories) by keyword, topic, or language	No
`get_project_info`	Get detailed project metadata (stars, description, languages, statistics)	No
`list_project_files`	List files and directories in a project's repository	No
`get_file_content`	Fetch the content of a specific file (includes binary detection)	No
`get_project_readme`	Get the README content for a project	No
`search_code`	Search for code within a specific project or globally	Yes*
`search_lhcb_stack`	Search for code within an LHCb software stack (e.g., 'sim11'), with automatic Git ref resolution	Yes*
`search_issues`	Search for issues in a project	Yes
`get_wiki_pages`	List wiki pages for a project	Yes
`inspect_project`	Analyze project structure, build system, dependencies, and CI/CD	No
`list_releases`	List releases for a project	No
`get_release`	Get details of a specific release	No
`list_tags`	List tags for a project	No
`test_connectivity`	Test connection to the GitLab instance	No

For detailed parameter documentation, see docs/dev.md.

Example Prompts

Search for repositories

"Search CERN GitLab for Python repositories related to ROOT analysis and show me the most starred ones"

Understand a project

"Get the README and file structure of the lhcb/DaVinci project on CERN GitLab"

Find fitting examples

"Search for repositories on CERN GitLab that use RooFit and show me example fitting code"

View LHCb software stack code

"Search the LHCb sim11 stack for the initialization routines in the Boole project"

Analyze a project structure

"Inspect the lhcb/allen project to understand its build system, dependencies, and CI pipeline configuration"

Find usage context

"Search for issues related to 'segmentation fault' in the atlas/athena project to see if others have encountered this"

Track releases

"List the recent releases of lhcb/DaVinci and show me the release notes for the latest version"

Find framework configurations

"Search for Gaudi framework configuration files on CERN GitLab and show me examples"

Development

See docs/dev.md for development setup, project structure, testing, and release instructions.

Multi-User HTTP Deployment

For centralized deployments serving multiple users, use HTTP mode:

Setup

# Start HTTP server
cerngitlab-mcp --mode http --host 0.0.0.0 --port 8080

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

User Authentication

For demo purposes, users can be configured via environment variables:

# Set up demo users
export CERNGITLAB_DEMO_USER_alice=glpat-alice-token
export CERNGITLAB_DEMO_USER_bob=glpat-bob-token

Users authenticate with Authorization: Bearer demo-alice header.

API Endpoints

GET / - Server information
GET /health - Health check
GET /tools - List available tools (authenticated)
POST /tools/{tool_name} - Execute specific tool (authenticated)
POST /mcp - Generic MCP endpoint (authenticated)

Example Usage

# List available tools
curl -H "Authorization: Bearer demo-alice" http://localhost:8080/tools

# Execute a tool
curl -X POST -H "Authorization: Bearer demo-alice" \
     -H "Content-Type: application/json" \
     -d '{"arguments": {"query": "ROOT"}}' \
     http://localhost:8080/tools/search_projects

CLI Tool

A command-line interface is also available for direct usage without the MCP server:

# 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

All commands output JSON to stdout for easy piping and composition. See cerngitlab-cli --help for the full list of commands.

Skill File

A detailed skill file (SKILL.md) is available with:

Complete documentation of all 14 tools
Input/output specifications
Usage examples
Authentication requirements

This can be used by LLMs or agents to understand the available tools and how to use them.

License

AGPL-3.0

Name		Name	Last commit message	Last commit date
Latest commit History 39 Commits
.github/workflows		.github/workflows
docs		docs
icons		icons
src/cerngitlab_mcp		src/cerngitlab_mcp
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.python-version		.python-version
README.md		README.md
SKILL.md		SKILL.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

CERN GitLab MCP Server

Features

Installation

Quickstart (recommended)

From PyPI

From source

Configuration

Authentication

Usage

Claude Desktop

Claude Code

GitHub Copilot

Gemini CLI

Direct usage

Stdio Mode (Single-User, Default)

HTTP Mode (Multi-User)

Mode Selection

Tools

Example Prompts

Search for repositories

Understand a project

Find fitting examples

View LHCb software stack code

Analyze a project structure

Find usage context

Track releases

Find framework configurations

Development

Multi-User HTTP Deployment

Setup

User Authentication

API Endpoints

Example Usage

CLI Tool

Skill File

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 8

Uh oh!

Contributors

Uh oh!

Languages