HEPData MCP

This is an MCP server for discovering HEPData records, listing tables, fetching table data, and exposing HEPData export links. This is an early MVP implementation, focused on read-only access to public HEPData content.

Local stdio is the default and recommended mode. HTTP support exists for local testing and hardened central deployments, but remote HTTP is also supported for multiple clients support.

Run From PyPI

HEPData MCP is published on PyPI as hepdata-mcp. The easiest way to run it is with uvx:

uvx hepdata-mcp

If you want to avoid package resolution during MCP client startup, install the tool once:

uv tool install hepdata-mcp
hepdata-mcp

Upgrade that installed tool with uv tool upgrade hepdata-mcp. For MCP client configs in this mode, use hepdata-mcp as the command with no arguments.

Install From Source

For development, install this checkout in editable mode:

git clone https://github.com/HEPData/hepdata-mcp ~/.local/uv/hepdata-mcp-src
cd ~/.local/uv/hepdata-mcp-src
uv sync --all-groups

For development checks:

uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy

Docker

The Docker image is published on Docker Hub as hepdata/hepdata-mcp. Pull the latest release:

docker pull hepdata/hepdata-mcp:latest

For reproducible deployments, pin a release tag such as hepdata/hepdata-mcp:0.1.0.

Run over stdio for clients that can launch Docker commands:

docker run --rm -i hepdata/hepdata-mcp:latest

Example stdio client command:

{
  "mcpServers": {
    "hepdata": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "hepdata/hepdata-mcp:latest"]
    }
  }
}

Run local streamable HTTP:

docker run --rm \
  -p 127.0.0.1:8000:8000 \
  -e HEPDATA_MCP_ALLOW_REMOTE_HTTP=1 \
  -e HEPDATA_MCP_TRUST_PROXY_AUTH=1 \
  hepdata/hepdata-mcp:latest \
  --transport streamable-http --host 0.0.0.0 --port 8000

The container runs as a non-root user. For remote HTTP deployment, keep the same reverse-proxy, TLS, authentication, and rate-limit requirements described below.

Build the image from this checkout for local development:

docker build -t hepdata-mcp:local .

Tools

• search_records
• get_record
• list_tables
• describe_table
• get_table
• get_record_exports
• get_record_versions
• get_jsonld
• server_info

Resources:

• hepdata://record/{identifier}
• hepdata://record/{identifier}/tables

Local MCP Client Setup

Most MCP clients launch commands directly, without a shell. Use uvx as the command and pass the package name as an argument.

Warm the uvx cache once before configuring a client, especially on machines with slow or restricted network access:

uvx hepdata-mcp --help

Useful variants:

uvx hepdata-mcp==0.1.0
uvx --refresh hepdata-mcp

If a GUI-launched client cannot find uvx, check where uvx is installed with command -v uvx and use that path as the command. On macOS this is commonly needed for clients such as Claude Code; Homebrew installs often use /opt/homebrew/bin/uvx, while standalone uv installs may use /Users/<you>/.local/bin/uvx. Use the expanded absolute path because MCP clients usually do not expand ~ or $HOME.

GitHub Copilot In VS Code

Create or edit .vscode/mcp.json:

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

Then run MCP: List Servers from the VS Code command palette and start hepdata.

For GitHub Copilot CLI:

copilot mcp add hepdata --type stdio -- uvx hepdata-mcp

Codex

Add to ~/.codex/config.toml:

[mcp_servers.hepdata]
command = "uvx"
args = ["hepdata-mcp"]
supports_parallel_tool_calls = true

Or, if using a local HTTP server:

codex mcp add hepdata --url http://127.0.0.1:8000/mcp

Claude Code

Project .mcp.json example:

{
  "mcpServers": {
    "hepdata": {
      "type": "stdio",
      "command": "uvx",
      "args": ["hepdata-mcp"]
    }
  }
}

On macOS, if Claude Code cannot find uvx, expand the command:

{
  "mcpServers": {
    "hepdata": {
      "type": "stdio",
      "command": "/opt/homebrew/bin/uvx",
      "args": ["hepdata-mcp"]
    }
  }
}

CLI alternative:

claude mcp add-json hepdata '{"type":"stdio","command":"uvx","args":["hepdata-mcp"]}'

Qwen Code

Add to ~/.qwen/settings.json or .qwen/settings.json:

{
  "mcpServers": {
    "hepdata": {
      "command": "uvx",
      "args": ["hepdata-mcp"],
      "timeout": 30000,
      "trust": false
    }
  }
}

Other MCP Clients

Most stdio MCP clients support a similar shape:

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

HTTP Mode

Start local streamable HTTP:

uvx hepdata-mcp --transport streamable-http --host 127.0.0.1 --port 8000

Local URL:

http://127.0.0.1:8000/mcp

Example VS Code / GitHub Copilot HTTP config:

{
  "servers": {
    "hepdata": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Example Qwen Code HTTP config:

{
  "mcpServers": {
    "hepdata": {
      "httpUrl": "http://127.0.0.1:8000/mcp",
      "timeout": 30000
    }
  }
}

Central Deployment

Remote HTTP binds are intentionally blocked unless both deployment opt-ins are set:

HEPDATA_MCP_ALLOW_REMOTE_HTTP=1 \
HEPDATA_MCP_TRUST_PROXY_AUTH=1 \
uvx hepdata-mcp --transport streamable-http --host 0.0.0.0 --port 8000

Only use this behind hardened ingress:

• TLS at the edge.
• Authentication and authorization before requests reach this process.
• Per-user or per-token rate limits.
• No request-body or table-payload logging.

Notes

• HEPData upstream access is public and read-only.
• Large tool payloads are truncated before being returned to agents.
• Whole-record download exports are returned as HEPData URLs, not downloaded by default.
• Live integration tests are opt-in:

HEPDATA_MCP_LIVE_TESTS=1 uv run pytest tests/test_live_client.py

License

This project follows the main HEPData project license: GNU General Public License version 2 or later (GPL-2.0-or-later). See LICENSE.