io.github.cyanheadsPublished by GitHub account cyanheadsv1.8.1Updated Oct 29, 2026
Search arXiv, fetch paper metadata, and read full-text content.
Searches arXiv, fetches paper metadata by ID, and reads full paper text, so an assistant can research and cite preprints.
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/io.github.cyanheads%2Farxiv-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"mcpServers": {
"arxiv": {
"type": "http",
"url": "https://arxiv.caseyjhand.com/mcp"
}
}
}Search arXiv, fetch paper metadata, and read full-text content via MCP. STDIO or Streamable HTTP.
Public Hosted Server: https://arxiv.caseyjhand.com/mcp
arXiv papers, metadata, and full text from the arXiv API and its OAI-PMH metadata feed. Search papers by query, category, and submission date; fetch structured metadata by ID; and read full paper text with automatic fallback across HTML and PDF renders. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
arxiv_search_papers toolti:, au:, abs:, cat:, co:, jr:, all: and AND / OR / ANDNOT, up to 1000 characters; category takes a code (cs.CL) or a whole archive (astro-ph, cs, math)OR (write AND to require every term), operators are uppercase only, and all three share one precedence grouped to the right (a AND b OR c is a AND (b OR c)). Quote a multi-word topic ("graph neural networks" AND cat:cs.LG) and put alternatives in parentheses before a filter; arXiv ignores common words such as of and the outside a quoted phrasesort_by (relevance / submitted / updated) and sort_order, with submitted_from / submitted_to as inclusive UTC YYYY-MM-DD bounds; up to 50 results per call (a larger max_results returns 50)start of 10,000 fails start_beyond_result_limit. Use date windows to go furthertotalFoundIsLowerBound: truearxiv_get_metadata toolremaining_ids for the next call's paper_ids. An ID repeated in any accepted spelling is looked up once, while different versions of one paper stay separate2401.12345v2), unversioned, and pre-2007 (hep-th/9901001) IDs, with an optional arXiv: prefix or an arxiv.org abs / pdf / html URLnot_found[] (not_in_arxiv / version_not_in_mirror / version_not_served / live_lookup_failed / invalid_id) for the rest; version_not_served is a superseded pre-2007 version arXiv's API answers HTTP 500 for, and its detail names the latest version. With the local mirror, live_lookup_failed marks an ID the mirror lacked whose live lookup failed; the papers the mirror served still come backinvalid_id when no ID is well-formed, no_match when every ID misses, version_unavailable when a version is reachable only on the live API, and version_not_served when every ID is a version arXiv will not servearxiv_read_paper toolsource field reports which answered. PDF text is plain, so math, tables, and headings flattenpaper_id and carries revision_unconfirmed: true, unless the read named no version and arXiv's API reported v1 as the paper's only version; pdf_url is exactly the paper_id revisionmax_characters defaults to 100,000 (pass null for the whole paper); page with start. The first page carries an outline of section headings with offsetspaper_id accepts the same ID spellings as arxiv_get_metadatainvalid_id, no_match (arXiv has no such paper, or no such version of it), content_unavailable (no render, no PDF), pdf_extraction_failed (the PDF has no text layer or does not parse), version_unavailable (version-pinned ID needs the live API), or version_not_served (a superseded pre-2007 version arXiv will not serve; names the latest version and this version's PDF)arxiv_list_categories toolcs, econ, eess, math, physics, q-bio, q-fin, stat)group filter to narrow resultsarxiv://paper/{paperId} resourcepaperId accepts the same ID spellings as arxiv_get_metadata; percent-encode a legacy ID's slash (arxiv://paper/hep-th%2F9901001)empty_id, invalid_id, no_match, version_unavailable, or version_not_servedarxiv://categories resource{ categories: [...] }, a flat array with code / name / group per entryBuilt on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.
arXiv-specific:
Agent-friendly output:
arxiv_read_paper names its source; arxiv_search_papers echoes the effective queryarxiv_get_metadata returns found papers with a typed not_found[] reason per misssource and not_found[].reason enums let callers branch on dataA public instance is available at https://arxiv.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:
Add the following to your MCP client configuration file.
Or with npx (no Bun required):
Or with Docker:
For Streamable HTTP, set the transport and start the server:
All configuration is optional — the server works out of the box with sensible defaults.
See .env.example for the full list of optional overrides.
Build and run:
Run checks and tests:
For self-hosted deployments behind one egress IP, an optional SQLite + FTS5 mirror of arXiv's OAI-PMH metadata serves arxiv_search_papers and arxiv_get_metadata locally, so concurrent users stop queueing behind arXiv's 3-second crawl delay; arxiv_read_paper still fetches paper text live. Harvest it once with bun run mirror:init (~4.4h), then set ARXIV_MIRROR_ENABLED=true. Running it from an npm install, scheduling refreshes, schema upgrades, and where mirror search differs from the live API are covered in docs/mirror.md.
The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/arxiv-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.
See CLAUDE.md for development guidelines and architectural rules. The short version:
try/catch in tool logicctx.log for request-scoped logging, ctx.state for tenant-scoped storageIssues are welcome. Run checks before submitting:
Apache-2.0 — see LICENSE for details.
Source: README.md at commit 50eae3a
Arxiv Search Papers
Search arXiv papers by query with category and sort filters. Returns paper metadata including title, authors, abstract, categories, and links.
queryrequiredstartsort_bycategorysort_ordermax_resultssubmitted_tosubmitted_fromArxiv Get Metadata
Get full metadata for one or more arXiv papers by ID. Use when you have known IDs from citations, prior search results, or memory. Looks up 10 IDs per call; any further IDs come back in remaining_ids for the next call.
paper_idsrequiredArxiv Read Paper
Fetch the full text of an arXiv paper. Tries arxiv.org/html first, falls back to ar5iv.labs.arxiv.org, and falls back again to text extracted from the PDF when neither has an HTML render — check the source field to know which one answered. Page through long papers with start and max_characters, or pass max_characters null to get the entire body in one call. To read one section, take the outline from the first page (start 0) and pass an entry's start.
startpaper_idrequiredmax_charactersArxiv List Categories
List arXiv category codes and names. Useful for discovering valid category filters for arxiv_search_papers. Lists subject classes only; arxiv_search_papers also accepts a bare archive code (the part before the dot, e.g. "astro-ph" or "cs") to search a whole archive at once.
group100% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
{ "mcpServers": { "arxiv-mcp-server": { "type": "streamable-http", "url": "https://arxiv.caseyjhand.com/mcp" } }}{ "mcpServers": { "arxiv-mcp-server": { "type": "stdio", "command": "bunx", "args": ["@cyanheads/arxiv-mcp-server@latest"] } }}{ "mcpServers": { "arxiv-mcp-server": { "type": "stdio", "command": "npx", "args": ["-y", "@cyanheads/arxiv-mcp-server@latest"] } }}{ "mcpServers": { "arxiv-mcp-server": { "type": "stdio", "command": "docker", "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/arxiv-mcp-server:latest"] } }}MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http# Server listens at http://localhost:3010/mcpgit clone https://github.com/cyanheads/arxiv-mcp-server.gitcd arxiv-mcp-serverbun install# One-time buildbun run rebuild
# Run the built serverbun run start:http# orbun run start:stdiobun run devcheck # Lint, format, typecheck, security auditbun run test # Vitest test suitedocker build -t arxiv-mcp-server .docker run --rm -p 3010:3010 arxiv-mcp-serverbun run devcheckbun run test