CDS MCP Server

A Model Context Protocol (MCP) server for integrating with CERN Document Server (CDS), built on the Invenio digital library framework.

[!WARNING] As of July 28, 2026, CDS places its public search, export, API, and OAI routes behind an Anubis JavaScript proof-of-work challenge. Non-browser clients receive HTML instead of record data, so this MCP server cannot currently query CDS. The CDS team must provide a machine-accessible route or exempt the documented API routes before service can be restored.

Features

• Search CDS documents with filters for experiments, document types, and date ranges
• Get detailed document information including full abstracts, authors, and metadata
• Access document files with download URLs and file metadata
• Browse experiments and document types for better search filtering

Installation

Requires Python 3.10+.

Quickstart (recommended)

No installation needed, just use uvx to run directly:

uvx cds-mcp

From PyPI

pip install cds-mcp

From source

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

Usage

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "cds": {
      "command": "uvx",
      "args": ["cds-mcp"]
    }
  }
}

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 cds-mcp -- uvx cds-mcp

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

claude mcp add --scope user cds-mcp -- uvx cds-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": {
    "cds": {
      "command": "uvx",
      "args": ["cds-mcp"]
    }
  }
}

GitHub Copilot

Add to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "cds": {
        "command": "uvx",
        "args": ["cds-mcp"]
      }
    }
  }
}

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

{
  "servers": {
    "cds": {
      "command": "uvx",
      "args": ["cds-mcp"]
    }
  }
}

Gemini CLI

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

{
  "mcpServers": {
    "cds": {
      "command": "uvx",
      "args": ["cds-mcp"]
    }
  }
}

Direct usage

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

# Or if installed from PyPI
cds-mcp

# Or from source
uv run cds-mcp

Authentication & Access Control

CDS does not document an API key or OIDC audience for its legacy /search JSON endpoint. Although this repository contains experimental CERN OIDC client-credentials code, obtaining a token does not authenticate a request to CDS: API-access tokens require a target audience that accepts the token, and a client-credentials token represents an application identity rather than the CERN user whose experiment memberships grant access to restricted records.

Do not create a Personal API request or OIDC application for this server until CDS Support confirms:

1. The supported machine-to-machine endpoint and authentication scheme.
2. The exact OIDC audience, if bearer tokens are supported.
3. Whether access to restricted records requires a user-delegated flow.
4. Which API paths are exempt from the Anubis browser challenge.

Tools

1. `search_cds_documents`: Search CDS with various filters
2. `get_cds_document_details`: Get detailed information about a specific document
3. `get_cds_document_files`: Get file information and download URLs
4. `get_cds_experiments`: List available CERN experiments for filtering
5. `get_cds_document_types`: List available document types for filtering

Development

git clone https://github.com/MohamedElashri/cds-mcp
cd cds-mcp
uv sync
uv run python tests/test_integration.py  # Test real CDS API integration
uv run python tests/test_mcp_server.py   # Test MCP server functionality

License

MIT License - see LICENSE for details.