# rxiv-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server that lets Claude (or any MCP client) search and read preprints on **arXiv**, **bioRxiv**, and **medRxiv**.

No API keys. No native dependencies. Runs over stdio with Node 20+.

## Tools

| Tool | What it does |
| --- | --- |
| `arxiv_search` | Search arXiv by plain text or raw arXiv query syntax (`ti:`, `au:`, `abs:`, `cat:`, booleans), with category and date filters. |
| `arxiv_get_paper` | Metadata and abstract for one or more arXiv IDs or URLs. |
| `arxiv_get_full_text` | Full text of a paper, from arXiv's HTML rendering (LaTeX math preserved) or the PDF. Paged. |
| `biorxiv_search` | Keyword search across bioRxiv and medRxiv, with server, date, and sort (relevance / date / citations) filters. |
| `biorxiv_get_preprint` | Official bioRxiv/medRxiv record for a DOI: all versions, license, category, and the published journal version if any. |
| `biorxiv_list_recent` | Browse what was posted in a date window, optionally by subject category. |
| `biorxiv_get_full_text` | Full text of a bioRxiv/medRxiv preprint (JATS XML or PDF). Paged. |

Full-text tools return up to `max_chars` characters (default 40,000) and report `truncated` and `next_offset` so the client can page through long papers.

## Install

### Claude Code

```bash
# from a local clone
git clone https://github.com/sakzgupzzz/rxiv-mcp.git
cd rxiv-mcp && npm install          # builds dist/ via the prepare script
claude mcp add --scope user rxiv -- node /absolute/path/to/rxiv-mcp/dist/index.js

# or straight from GitHub, no clone
claude mcp add --scope user rxiv -- npx -y github:sakzgupzzz/rxiv-mcp
```

### Claude Desktop / other MCP clients

Add to `claude_desktop_config.json` (or the equivalent for your client):

```json
{
  "mcpServers": {
    "rxiv": {
      "command": "npx",
      "args": ["-y", "github:sakzgupzzz/rxiv-mcp"]
    }
  }
}
```

## Examples of what to ask

- "Find the five most-cited bioRxiv preprints on CRISPR base editing from 2025."
- "What was posted to medRxiv in epidemiology in the last three days?"
- "Read arXiv 2410.12345 and summarise the method section."
- "Has bioRxiv 10.1101/2025.05.19.654892 been published in a journal?"

## How it works

- **arXiv** uses the official [arXiv API](https://info.arxiv.org/help/api/) (Atom feed). Requests are spaced at least 3 seconds apart per arXiv's rate-limit guidance. Full text comes from `arxiv.org/html/<id>` when the paper has an HTML rendering, otherwise the PDF is parsed with [unpdf](https://github.com/unjs/unpdf).
- **bioRxiv / medRxiv** metadata, version history, and published-version lookups use the official [bioRxiv API](https://api.biorxiv.org/). That API has no keyword search and only lists by DOI or date range, so:
  - **Search** goes through [Europe PMC](https://europepmc.org/RestfulWebService), which indexes every bioRxiv and medRxiv preprint with abstracts and citation counts. You can use Europe PMC query syntax directly (`TITLE:"..."`, `AUTH:"..."`, `ABSTRACT:"..."`).
  - **Full text** also comes from Europe PMC (JATS XML, then PDF), because biorxiv.org rate-limits scripted downloads. Full text typically appears there a few days after a preprint is posted.
- Every outbound request carries a descriptive User-Agent, is throttled per host, and retries on 429/5xx.

## Development

```bash
npm install
npm run build        # tsc -> dist/
npm test             # starts the server, checks the tool list (offline)
npm run smoke        # exercises every tool against the live APIs
```

Source layout:

```
src/index.ts     server entry (stdio)
src/tools.ts     tool definitions and input schemas
src/arxiv.ts     arXiv API client + full text
src/biorxiv.ts   bioRxiv API + Europe PMC clients
src/text.ts      HTML / JATS to text, paging
src/pdf.ts       PDF text extraction
src/http.ts      fetch wrapper: throttling, retries, User-Agent
```

## License

MIT