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
• CLI tool (cerngitlab-cli) for direct command-line usage
• 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

#