# 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](https://docs.astral.sh/uv/) to run directly:

```bash
uvx cds-mcp
```

### From PyPI

```bash
pip install cds-mcp
```

### From source

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

## Usage

### Claude Desktop

Add to your `claude_desktop_config.json`:

```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:

```json
"command": "/Users/yourusername/.local/bin/uvx"
```

### Claude Code

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

```bash
claude mcp add cds-mcp -- uvx cds-mcp
```

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

```bash
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):

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

### GitHub Copilot

Add to your VS Code `settings.json`:

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

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

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

### Gemini CLI

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

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

### Direct usage

```bash
# 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

```bash
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](LICENSE) for details.