ChinaRxiv MCP Server

FastMCP server for the ChinaRxiv API.

Tools

• search_papers
• get_paper_detail
• get_paper_full_text
• get_paper_figures
• download_paper_pdf
• list_subjects
• list_publications
• get_api_stats
• list_bulk_exports
• health_check

Agent-friendly behavior

• list_subjects(q, limit, offset, cache_bust, api_email) filters and paginates locally. Upstream is cached for 1 hour.
• list_publications(q, limit, offset, cache_bust, api_email) lists journal keys accepted by the publication search filter. Upstream is cached for 1 hour.
• download_paper_pdf(paper_id, include_base64, api_email) returns metadata by default: URL, content type, byte size, SHA-256 checksum, and a future resource URI. It only includes base64 when include_base64=true.
• search_papers(...) supports the official field, date, availability, source, language, and publication filters. Pagination uses cursor.
• Most tools accept optional api_email to override CHINARXIV_EMAIL for the upstream X-API-Email header.
• API rate-limit headers are returned as rate_limit metadata when provided upstream.
• Cache TTLs: subjects/publications 1h, stats 10min, bulk exports 6h, paper detail/text/figures/pdf 24h.

Tests

uv run pytest

Configuration

Create your local environment file from the provided example:

Copy-Item .env.example .env

Then edit .env with the values for your environment. The server loads this file automatically on startup. Variables already defined in the process environment take precedence over .env.

Local stdio

uv run python server.py

Docker

docker build -t mcp-chinarxiv .
docker run --rm -i --env-file .env mcp-chinarxiv

Hermes

If Hermes supports MCP over HTTP, run the container as a local service:

docker run -d --name mcp-chinarxiv -p 8765:8765 --env-file .env mcp-chinarxiv uv run fastmcp run server.py:mcp --transport http --host 0.0.0.0 --port 8765

Then add this server URL in Hermes:

{
  "mcpServers": {
    "chinarxiv": {
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

If Hermes expects stdio MCP servers, let Hermes launch Docker directly:

{
  "mcpServers": {
    "chinarxiv": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env-file",
        ".env",
        "mcp-chinarxiv"
      ]
    }
  }
}

Environment

• CHINARXIV_BASE_URL: defaults to https://chinarxiv.org
• CHINARXIV_EMAIL: email sent in the upstream X-API-Email header
• CHINARXIV_TIMEOUT: defaults to 30
• CHINARXIV_USER_AGENT: defaults to mcp-chinarxiv/0.1