Skip to main content

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

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

Metadata

Release files for hepdata-mcp 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hepdata-mcp 0.2.1
File Size Uploaded Provenance Actions
hepdata_mcp-0.2.1.tar.gz 108.6 kB With provenance Details for hepdata_mcp-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hepdata-mcp 0.2.1
File Interpreter ABI Platform Actions
hepdata_mcp-0.2.1-py3-none-any.whl Python 3 none any Details for hepdata_mcp-0.2.1-py3-none-any.whl

Total release size: 136.8 kB

Release files / hepdata_mcp-0.2.1.tar.gz

Download URL hepdata_mcp-0.2.1.tar.gz
Size 108.6 kB
Tags Source
SHA-256 checksum
How to use checksums
b260b76c2b5e0b53db75d68b165ddf6a2533413110e8b557786eaf728cbec3db
BLAKE2b-256 checksum
How to use checksums
797c6cfaa833fc1c20d23618fe4447b0fb5a8cb2bd20b3301142f59e1a3b0957
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / hepdata_mcp-0.2.1-py3-none-any.whl

Download URL hepdata_mcp-0.2.1-py3-none-any.whl
Size 28.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bdda2c1551132a1fa4bbc15428a3531d603cd10fc01a187fa1ef7e2289806610
BLAKE2b-256 checksum
How to use checksums
315c71c154610b3b06d76d7e08fad48cc2a6c8e743ea1df7b60a6370fbe60a8e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for hepdata-mcp 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for hepdata_mcp-0.2.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page