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