arxiv-mcp-server

by cyanheads

Not rated
GitHub

About

arXiv paper search and full-text reading

Details

Author
cyanheads
Categories
Productivity, Search, Knowledge Base

Setup

Install arxiv-mcp-server in your MCP client (Claude Desktop, Cursor, Windsurf, and others).

Repository: https://github.com/cyanheads/arxiv-mcp-server

Follow the installation instructions in the repository README, then restart your MCP client.

Search arXiv, fetch paper metadata, and read full-text content via MCP. STDIO or Streamable HTTP.

Public Hosted Server:https://arxiv.caseyjhand.com/mcp

Four tools for searching and reading arXiv papers:

Search for papers using free-text queries with field prefixes and boolean operators.

- Field prefixes:ti:(title),au:(author),abs:(abstract),cat:(category),all:(all fields)
- Boolean operators:AND,OR,ANDNOT
- Optional category filter, sorting (relevance, submitted, updated), and pagination
- Category accepts a leaf code (cs.CL) or a whole archive (astro-ph,cs,math) — a bare archive covers its subject classes plus the legacy flat papers filed before it was subdivided
- submitted_from/submitted_tobound the submission date (inclusive, UTCYYYY-MM-DD). Consecutive windows cover the matches with no gap — a paper submitted exactly at a midnight seam falls in both, so de-duplicate by ID — which is how to reach results past the 10,000 pagination ceiling
- Echoes back the query as actually searched, with every filter folded in — replaying it reproduces the same result set
- Returns up to 50 results per request with full metadata including abstract

Fetch full metadata for one or more papers by known arXiv ID.

- Batch fetch up to 10 papers in a single request
- Accepts both versioned (2401.12345v2) and unversioned (2401.12345) IDs
- Legacy ID format supported (hep-th/9901001)
- Reports not-found IDs separately from found papers

- Tries native arXiv HTML first, then ar5iv, then text extracted from the PDF — thesourcefield reports which one answered
- Strips HTML head/boilerplate and collapses MathML to dollar-delimited LaTeX ($…$inline,$$…$$block) so the character budget targets paper content
- Returns raw HTML — no parsing or extraction; the LLM interprets content directly. PDF-extracted bodies are plain text: prose is reliable, but math, tables, and heading structure flatten
- max_charactersdefaults to 100,000; passnullfor the whole paper in one call. Raw HTML can be 500KB-3MB+ for math-heavy papers, which is more than most clients accept in a single tool result — page withstartinstead

List arXiv category codes and names for discovery.

- ~155 categories across 8 top-level groups (cs, math, physics, q-bio, q-fin, stat, eess, econ)
- Optional group filter to narrow results
- Static data — always succeeds

- Declarative tool definitions — single file per tool, framework handles registration and validation
- Unified error handling across all tools
- Pluggable auth (none,jwt,oauth)
- Structured logging with optional OpenTelemetry tracing
- Runs locally (stdio/HTTP) from the same codebase

- Read-only, no authentication required — arXiv API is free, metadata is CC0
- Rate-limited request queue enforcing arXiv's 3-second crawl delay
- Adaptive cooldown on rate-limit (5s → 10s → 20s → 30s), honorsRetry-After
- Retry with exponential backoff for transient failures
- Content fallback chain: native arXiv HTML → ar5iv → PDF text extraction (both HTML renders run LaTeXML, so they tend to fail together; the PDF is the artifact every paper has, and it also covers an ar5iv outage rather than letting one fail the read)
- Full arXiv category taxonomy embedded as static data
- Optional local OAI-PMH metadata mirror (SQLite + FTS5) — opt-in, eliminates rate-limit exposure forarxiv_searchandarxiv_get_metadata. See
Optional: Local Mirror.

A public instance is available athttps://arxiv.caseyjhand.com/mcp— no installation required. Point any MCP client at it via Streamable HTTP:

{ "mcpServers": { "arxiv-mcp-server": { "type": "streamable-http", "url": "https://arxiv.caseyjhand.com/mcp" } } }

Add to your MCP client config (e.g.,claude_desktop_config.json):

{ "mcpServers": { "arxiv-mcp-server": { "type": "stdio", "command": "bunx", "args": ["@cyanheads/arxiv-mcp-server@latest"] } } }
git clone https://github.com/cyanheads/arxiv-mcp-server.git

All configuration is optional — the server works out of the box with sensible defaults.

bun run build bun run start:http # or start:stdio
bun run devcheck # Lint, format, typecheck, audit bun run test # Vitest

For self-hosted deployments behind a single egress IP, arXiv's ~3-second per-IP crawl delay serializes concurrent users. An optional local mirror eliminates rate-limit exposure forarxiv_searchandarxiv_get_metadataby serving from a SQLite + FTS5 store harvested via OAI-PMH.arxiv_read_papercontinues to use the live API — full-content harvest is forbidden by arXiv's data policy.

# 1. Cold-start harvest (~4.4h sequential, resumable from checkpoint). One-time per installation. bun run mirror:init # 2. Enable the mirror. export ARXIV_MIRROR_ENABLED=true # 3. Start the server — reads switch to the mirror once the harvest completes. bun run start:http

Daily incremental refresh (small delta; duration depends on arXiv's OAI-PMH page pacing) via:

bun run mirror:refresh # wire to cron / systemd timer / launchd, OR # set ARXIV_MIRROR_REFRESH_CRON to schedule it in HTTP mode (spawned as a child process) bun run mirror:verify # schema version + PRAGMA integrity_check / quick_check

Schema upgrades.The mirror records a schema version and migrates itself in place the first time a newer server opens it — never a re-harvest, and never a separate operator step. The upgrade that addedcommentandjournal_refto the full-text index (#37) rebuilds that index from the rows already stored, soco:andjr:searches resolve against a mirror harvested before it. The rebuild runs at startup, before the store answers its first read, and logsmirror migration v2→v3 (fts rebuild)progress lines throughout — on a full-corpus mirror, expect the first start after the upgrade to take noticeably longer than usual. An interrupted rebuild is repeated on the next open rather than left half-applied.bun run mirror:verifyprints the schema version the file carries and exits non-zero if a migration never completed.

Behavior notes.Ranking divergence: FTS5 BM25 differs from arXiv's internal ranking, sosortBy=relevanceagainst the mirror returns a different top-K than the live API. Queries sorted bysubmitteddescending withinARXIV_MIRROR_RECENT_DAYS_LIVEdays route to the live API to cover the nightly-update gap. Refresh resilience: after the initial cold harvest completes, an in-progress or failed daily refresh keeps serving the existing dataset from the mirror —arxiv_searchandarxiv_get_metadatadon't drop to the live API during the refresh window (#21). The scheduled HTTP-mode refresh runs in a child process, so the harvest's synchronous SQLite writes never block the request event loop — search and metadata stay responsive throughout (#22). The mirror stores the latest version only; per-version reads continue to use the live API. See#12for the full design.

docker build -t arxiv-mcp-server . docker run -p 3010:3010 arxiv-mcp-server

SeeCLAUDE.mdfor development guidelines and architectural rules. The short version:

- Handlers throw, framework catches — notry/catchin tool logic
- Usectx.logfor domain-specific logging
- Rate limiting is managed byArxivService— don't add per-tool delays
- arXiv API returns HTTP 200 for everything — check content-type and response body

Issues and pull requests are welcome. Run checks before submitting:

JobYap aggregates job postings directly from companies' official careers sites and gives every posting a public discussion thread, with salaries, locations and full descriptions.

Japanese government procurement bid search and AI analysis via MCP

Prompt Buddy MCP exposes a public, searchable catalog of reusable AI skills.

AI job search & hiring MCP server with 55 tools. Search jobs, apply, interview, negotiate offers across 20 countries. No account needed to start.

Interact with Amazon services for product search, cart management, and viewing order history.

MCP server for Apple Notes with semantic search and CRUD operations. Claude searches, reads, creates, updates, and manages your Apple Notes through natural language.

Birdfeeder: X, Bluesky and Mastodon bookmarks search

Search through your X, Bluesky or Mastodon bookmarks.

Conduit is the MCP for agentic commerce. Agents register an identity, search ranked supply across 12k+ merchants, complete checkout via merchant handoff or autonomous payment with an approved mandate, then track orders and report outcomes.

Integrate with Atlassian Confluence to access spaces, search pages, and manage content from any MCP-compatible application.

Programmatically access and search Confluence spaces, pages, and content using its REST API.

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.