CERN GitLab MCP Server

Features

• 14 MCP tools for searching, browsing, and analyzing CERN GitLab repositories

• Public access — works without authentication for public repositories

• 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_:

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:

1. Go to https://gitlab.cern.ch/-/user_settings/personal_access_tokens

2. Create a token with read_api scope

3. 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.

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

2. 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

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

# Or if installed from PyPI
cerngitlab-mcp

# Or from source
uv run cerngitlab-mcp

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

Tools

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.

License

AGPL-3.0