README.md
arxiv-mcp
An MCP server that exposes arXiv paper search, full-text HTML retrieval, and PDF download as tools. Built with FastMCP and served over SSE.
Tools
| Tool | Description |
|---|---|
search_papers |
Search arXiv for papers matching a query. Returns titles, authors, abstracts, and links. |
get_paper_html |
Retrieve the full text of an arXiv paper as HTML via ar5iv. |
download_pdf |
Download an arXiv paper as PDF to a specified directory (default: ./downloads). |
Quickstart
Requires Python 3.13+ and uv.
uv sync
uv run arxiv-mcp
The server starts on http://0.0.0.0:8613.
Options
| Flag | Description | Default |
|---|---|---|
--port |
Port to listen on | 8613 |
--output-dir |
Default PDF download directory | ./downloads |
uv run arxiv-mcp --port 9000 --output-dir /tmp/papers
The output_dir parameter on the download_pdf tool overrides the server default when provided.
Docker Compose
docker compose up --build
Downloads are persisted to ./downloads on the host via a bind mount.
MCP client configuration
Add the server to your MCP client config:
{
"mcpServers": {
"arxiv": {
"url": "http://localhost:8613/sse"
}
}
}
Development
uv sync # Install dependencies (including dev)
uv run pytest # Run tests
uv run ruff check # Lint
uv run ruff format # Format
uv run pyright # Type check
Architecture
src/arxiv_mcp/
domain.py - Pydantic models (Paper)
client.py - arXiv API wrapper (search, HTML via ar5iv, PDF download)
server.py - FastMCP server exposing the three tools
Tools 3
search_papersSearch arXiv for papers matching a query.get_paper_htmlRetrieve the full text of an arXiv paper as HTML via ar5iv.download_pdfDownload an arXiv paper as PDF to a specified directory.Try it
→Search for recent papers on transformer architecture improvements.
→Get the full text of the paper with ID 2401.00000 and summarize the methodology.
→Download the PDF for the paper 2401.00000 to my local downloads folder.