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

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.