arxiv-mcp

An MCP server that lets any coding agent search arXiv and download papers. Free, no API key, two tools.

Tools

Tool	What it does
search_arxiv(query, max_results=10)	Free-text search. Returns title, authors, abstract, date, PDF URL. No PDF parsing.
download_paper(arxiv_id)	Streams a PDF into ./papers/<id>.pdf. Idempotent.

Both are read-only on the network side. The server touches arXiv's public API (export.arxiv.org) — no key, no signup, no rate-limit token.

Install

git clone https://github.com/vishal24p/arxiv_mcp.git
cd arxiv_mcp
uv venv
uv pip install -e .

Requires Python 3.10+ and uv.

Wire it into your agent

The arxiv-mcp script is installed into the venv at .venv\Scripts\ (Windows) or .venv/bin/ (macOS/Linux). Activate first, or call it by path:

# Activate (then `arxiv-mcp` is on PATH)
# Windows (PowerShell):
.venv\Scripts\Activate.ps1
# Windows (cmd):
.venv\Scripts\activate.bat
# macOS / Linux:
source .venv/bin/activate

arxiv-mcp install                # auto-detect and patch all found agents
arxiv-mcp install --only codex   # one specific agent
arxiv-mcp install --dry-run      # show what would change, write nothing

If you skip activation, invoke the executable directly:

# Windows
.venv\Scripts\arxiv-mcp.exe install
# macOS / Linux
.venv/bin/arxiv-mcp install

Supported agents:

Agent	Config file	Format
Claude Desktop	%APPDATA%\Claude\claude_desktop_config.json	JSON
Claude Code	~/.claude.json	JSON
Cursor	~/.cursor/mcp.json	JSON
Codex CLI	~/.codex/config.toml	TOML

The installer merges an arxiv entry into each detected config, backs up the original to <file>.bak, and never touches other settings. It is idempotent — re-running with the same flag reports the entry already exists and writes nothing. Restart the agent and the tools appear.

Use

Ask the agent anything that needs arXiv:

find 3 papers on mixture of experts
download 1706.03762
what's the most cited recent paper on RLHF?

The agent picks search_arxiv or download_paper based on what you ask. PDFs land in ./papers/. Override the location with ARXIV_MCP_PAPERS_DIR.

Run without installing to an agent

arxiv-mcp serve
# ...or:
python -m arxiv_mcp

Speaks MCP over stdio. Useful for testing or wiring into something that isn't a coding agent.

Troubleshooting

arxiv-mcp is not recognized as the name of a cmdlet / command

The script lives in the venv at .venv\Scripts\arxiv-mcp.exe (Windows) or .venv/bin/arxiv-mcp (macOS/Linux). It is only on PATH while the venv is active. Either activate the venv first, or invoke the executable by its full path (see Wire it into your agent above).

The script name uses a hyphen (arxiv-mcp), not an underscore (arxiv_mcp). The Python package is arxiv_mcp; the console script is arxiv-mcp.

Re-running arxiv-mcp install reports the entry already exists

That is the intended idempotent behavior. Backups are at <config>.bak next to each original file. To force a fresh install, delete the arxiv key from the relevant config and re-run.

License

Apache 2.0.