InspireHEP MCP Server

An MCP server that integrates InspireHEP high-energy physics literature with LLMs. Search papers, explore citations, retrieve author metrics, and generate formatted references.

Installation

# Using pip
pip install inspirehep-mcp

# Or run directly with uvx (no install needed)
uvx inspirehep-mcp

Install from source

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

Remote endpoint deployment

The installed command remains a stdio server by default, so existing desktop

configurations continue to work. To run it natively as a remote MCP endpoint,

select the Streamable HTTP transport:

INSPIREHEP_ALLOWED_HOSTS="mcp.example.org" \
  INSPIREHEP_HTTP_RATE_LIMIT=60 \
  inspirehep-mcp --transport streamable-http --host 0.0.0.0 --port 8000

The MCP endpoint is `http://localhost:8000/mcp` and the unauthenticated health

probe is `http://localhost:8000/health`. `PORT` is also honored when a hosting

platform injects it. Put the service behind HTTPS for internet deployment.

Docker

Release tags publish a container to the GitHub Container Registry. The image

uses Streamable HTTP by default:

docker run --rm -p 8000:8000 \
  ghcr.io/mohamedelashri/inspirehep-mcp:latest

For a public hostname, add it to the host allowlist:

docker run --rm -p 8000:8000 \
  -e INSPIREHEP_ALLOWED_HOSTS="mcp.example.org" \
  -e INSPIREHEP_HTTP_RATE_LIMIT=60 \
  ghcr.io/mohamedelashri/inspirehep-mcp:latest

The image runs as a non-root user, has a built-in health check, and uses

stateless JSON responses so replicas do not need shared MCP session state.

Docker Compose

The included `docker-compose.yml` can build the current

checkout or run the published image:

# Local deployment
docker compose up --build -d

# Add the public hostname when deploying behind a domain
INSPIREHEP_ALLOWED_HOSTS="mcp.example.org" docker compose up -d

The Compose service is read-only, drops Linux capabilities, enables

`no-new-privileges`, and retains the image health check.

Inbound rate limiting

Streamable HTTP requests are limited per client IP with a token bucket. The

default is 60 requests per minute with a burst of 20; `/health` is exempt. Set

`INSPIREHEP_HTTP_RATE_LIMIT=0` to disable it.

Requests to `/mcp` are limited to 256 KiB. The native server also accepts at

most 100 concurrent connections or tasks, closes idle keep-alive connections

after 5 seconds, and admits at most 32 pending INSPIRE API cache misses. Excess

upstream work fails fast instead of accumulating in memory.

By default, the limiter uses the direct peer address and ignores forwarded

headers. Only enable `INSPIREHEP_TRUST_PROXY_HEADERS` when a trusted reverse

proxy overwrites `X-Forwarded-For`; otherwise clients can choose their own

rate-limit identity. The limiter is in-memory and per process, so multi-replica

deployments should also enforce a shared limit at the proxy or gateway.

> [!IMPORTANT]

> Read-only tools avoid mutation risk, but a public endpoint can still be used

> to consume your compute and upstream API allowance. This server does not add

> authentication. Use an authenticating reverse proxy if the endpoint should

> not be open to everyone, and retain an edge rate limit for distributed

> deployments. Keep DNS-rebinding protection enabled and set

> `INSPIREHEP_ALLOWED_ORIGINS` for clients that send an Origin header.

Integration

Claude Desktop / Cursor

Add to your MCP client config:

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

Claude Code

Option A: Using the CLI

# Global scope (available across all projects)
claude mcp add --scope user inspirehep -- uvx inspirehep-mcp

# Project scope (shared via .mcp.json, checked into source control)
claude mcp add --scope project inspirehep -- uvx inspirehep-mcp

Option B: Manual configuration

For global scope, add to `~/.claude.json`:

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

For project scope, create `.mcp.json` in your project root:

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

Antigravity CLI

Open the interactive MCP manager with `/mcp`, or configure the server manually.

Antigravity reads global MCP servers from `~/.gemini/config/mcp_config.json`

and workspace-local servers from `.agents/mcp_config.json`:

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

Tools

Configuration

All settings via environment variables (prefix `INSPIREHEP_`):

Development

# Run tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=inspirehep_mcp --cov-report=term-missing

# Unit tests only (no network)
uv run pytest tests/test_utils.py tests/test_cache.py tests/test_errors.py \
  tests/test_config.py tests/test_rate_limit.py tests/test_server.py \
  tests/test_api_client_safety.py tests/test_tools_safety.py

LICENCE

This project is licensed under the AGPL-3.0 License - see the LICENSE file for details.