arxiv-mcp-server

A local MCP server for agent literature work. The differentiator is original-LaTeX section reads, BibTeX from arXiv metadata, and topic watches. Papers stay on disk. The working loop is paper ID → outline → one section → citations. Search is optional.

Install

The default install is uvx arxiv-mcp-server. Command-based integrations need uv, which provides uvx. No repository clone or Python environment setup is required.

uvx arxiv-mcp-server

Add this stdio configuration to clients that accept the mcpServers JSON shape, such as Claude Desktop and Kiro. Other clients may use a top-level servers object, TOML, or their own settings UI; consult the client's MCP documentation.

{
  "mcpServers": {
    "arxiv": {
      "type": "stdio",
      "command": "uvx",
      "args": ["arxiv-mcp-server"]
    }
  }
}

The default paper directory is ~/.arxiv-mcp-server/papers. To choose another directory, append "--storage-path", "/absolute/path/to/papers" to args.

The supported package is published on PyPI as arxiv-mcp-server==0.8.2. An unrelated npm package uses the same name, so do not install this server with npm, pnpm, or npx arxiv-mcp-server.

Listed on the official MCP registry, latest 0.8.2.

Why this is not a search wrapper

Search, source retrieval, citation graphs, and downloads call their respective external services. What stays local is the literature loop: read author-submitted LaTeX one section at a time, export BibTeX from authoritative arXiv metadata, and keep topic watches on disk. The server runs locally over stdio by default.

claude mcp add --transport stdio --scope user arxiv -- uvx arxiv-mcp-server

claude plugin marketplace add blazickjp/arxiv-mcp-server
claude plugin install arxiv-mcp-server@arxiv-mcp

codex mcp add arxiv -- uvx arxiv-mcp-server

codex plugin marketplace add blazickjp/arxiv-mcp-server
codex plugin add arxiv-mcp-server@arxiv-mcp

hermes mcp add arxiv --command uvx --args arxiv-mcp-server
hermes mcp test arxiv

https://github.com/blazickjp/arxiv-mcp-server

If a desktop client cannot find uvx

Desktop applications do not always inherit the same PATH as your terminal. If uvx arxiv-mcp-server works in a terminal but the client reports that the server failed to connect, find the executable's absolute path:

# macOS and Linux
command -v uvx

# Windows PowerShell
(Get-Command uvx).Source

Replace "command": "uvx" with the returned absolute path, then restart the client. Keep the args value unchanged.

If an existing installation is missing newer tools

uvx reuses cached tool environments. Force it to resolve the current PyPI release with a supported interpreter, then restart your MCP client:

uvx --python 3.11 --refresh-package arxiv-mcp-server arxiv-mcp-server

If your client still launches an older environment, add "--python", "3.11" before "arxiv-mcp-server" in its args array.

Persistent command install

To place arxiv-mcp-server on your PATH instead of launching it through uvx:

uv tool install arxiv-mcp-server

If the command is not immediately available, run uv tool update-shell and restart the terminal. Afterward, use "command": "arxiv-mcp-server" and omit the package name from args.

Tools

The server currently exposes 19 tools.

Research alerts (watch_topic)

Save standing topic watches with watch_topic, inspect them with list_watches, poll with check_alerts, and remove with unwatch_topic.

When updating an existing watch (same topic string):

• Omit categories → preserve the stored category filters (and other fields you leave unchanged).
• Pass categories: [] → clear category filters.
• Pass a non-empty list → replace the stored filters.

Create path: omitting categories stores an empty list (no category filter).

search_papers query guide

Tool schemas stay short on purpose. Use this section (not the always-loaded MCP description) for query tutorials, category catalogs, and workflow examples.

Query construction

• Use quoted phrases for exact matches: "multi-agent systems", "neural networks"
• Combine related concepts with OR: "AI agents" OR "software agents"
• Field-specific searches: ti:"exact title phrase", au:"author name", abs:"keyword", cat:cs.LG
• Exclude with ANDNOT: "machine learning" ANDNOT "survey"
• Prefer 2–4 core concepts over long keyword lists

Advanced patterns

• Field + phrase: ti:"transformer architecture"
• Multiple fields: au:"Smith" AND ti:"quantum"
• Exclusions: "deep learning" ANDNOT ("survey" OR "review")
• Broad + narrow: "artificial intelligence" AND (robotics OR "computer vision")

Category filtering (recommended for relevance)

Computer Science: cs.AI (AI), cs.LG (ML), cs.CL (NLP), cs.CV (vision), cs.MA (multi-agent), cs.RO (robotics), cs.NE (neural/evolutionary), cs.IR (IR), cs.HC (HCI), cs.CR (security), cs.DB (databases)

Statistics & Math: stat.ML, stat.AP, math.OC, math.ST

Physics & other: quant-ph, eess.SP, eess.AS, physics.data-an

Effective examples

• ti:"reinforcement learning" with categories: ["cs.LG", "cs.AI"]
• au:"Hinton" AND "deep learning" with categories: ["cs.LG"]
• "multi-agent" ANDNOT "survey" with categories: ["cs.MA"]
• abs:"transformer" AND ti:"attention" with categories: ["cs.CL"]

Dates and sorting

• Dates use YYYY-MM-DD (date_from / date_to)
• Default sort_by is relevance; use date for newest-first monitoring
• Foundational work: date_to: "2010-12-31" with title/abstract field searches

Result size, abstracts, and pagination

• Default max_results is 5 (cap 50). Pass an explicit value for larger pages.
• abstract_mode: snippet (default, ~280 chars, marked … [truncated] when cut), full (complete abstract), or none (omit abstracts). Other metadata (title, authors, categories, dates, URLs) is always returned.
• Responses report total_results (corpus hits), returned, has_more, start, next_start, and abstract_mode
• Pass start=next_start with the same abstract_mode for the next page
• arXiv enforces ~3 seconds between requests (handled server-side); on rate-limit errors wait ~60s

Search and inspect a paper

Ask your MCP client to call search_papers with:

{
  "query": "\"Kolmogorov-Arnold Networks\"",
  "categories": ["cs.LG", "cs.AI"],
  "sort_by": "date"
}

Defaults return up to five compact results with abstract snippets. Use "abstract_mode": "full" when you need complete abstracts in the search response, or call get_abstract for a single paper after a compact search:

{
  "paper_id": "2404.19756"
}

Do not call get_abstract again for papers already returned with abstract_mode=full.

Download and read full text

Call download_paper with:

{
  "paper_id": "2404.19756"
}

Omitting max_chars returns a bounded first chunk (default 12,000 paper characters). Cached papers are returned immediately. Pass "force": true to re-download and overwrite the local markdown and sidecar (also happens automatically when the HTML extractor version changes).

Then page through the cached content with read_paper:

{
  "paper_id": "2404.19756",
  "start": 0
}

Or continue from a prior chunk:

{
  "paper_id": "2404.19756",
  "start": 12000
}

Large-content responses include content_length, returned_chars, next_start, is_truncated, and (when truncated) next_retrieval with the next-call instruction. Pass next_start into the next call's start to continue reading. Pass an explicit max_chars to override the default chunk size, or "return_full_text": true to opt into the previous unbounded full-paper response.

Migration notes (bounded content default)

Previously, omitting max_chars on download_paper / read_paper returned the entire paper. That default is now a 12,000-character chunk so a single MCP tool call cannot flood the client context window.

Clients that already passed max_chars are unchanged. Only callers that relied on the omitted-max_chars = full-text behavior need to add return_full_text: true or page via next_start.

Read original LaTeX by section

Call get_paper_latex with:

{
  "paper_id": "1706.03762"
}

Get the first page of its section outline with list_paper_latex_sections:

{
  "paper_id": "1706.03762",
  "start": 0,
  "max_sections": 100
}

Then call get_paper_latex_section using an ID from that outline:

{
  "paper_id": "1706.03762",
  "section_id": "3.2",
  "max_chars": 12000
}

LaTeX archives are validated, size-limited, and cached locally before content is returned.

Optional dependencies

Choose the install variant that matches the features you need:

# Base server
uv tool install arxiv-mcp-server

# Base server plus PDF conversion
uv tool install "arxiv-mcp-server[pdf]"

# Base server plus local semantic search
uv tool install "arxiv-mcp-server[pro]"

If the base tool is already installed, reinstall the selected variant:

uv tool install --force "arxiv-mcp-server[pdf]"

The pdf extra installs pymupdf4llm and pymupdf-layout for papers without usable arXiv HTML. The pro extra adds local embedding dependencies for semantic_search and reindex; semantic search only operates on papers already downloaded to the configured storage directory.

For older papers that require PDF conversion, run the package with its PDF extra:

{
  "mcpServers": {
    "arxiv": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "arxiv-mcp-server[pdf]",
        "arxiv-mcp-server"
      ]
    }
  }
}

Built-in prompts

The server provides seven MCP prompt workflows. Prompt availability depends on the client; the server provides workflow instructions but does not run a separate model.

Streamable HTTP

For deployments where stdio is not practical:

TRANSPORT=http HOST=127.0.0.1 PORT=8080 \
  uvx arxiv-mcp-server --storage-path /absolute/path/to/papers

PowerShell:

$env:TRANSPORT = "http"
$env:HOST = "127.0.0.1"
$env:PORT = "8080"
uvx arxiv-mcp-server --storage-path C:\absolute\path\to\papers

Connect clients to:

{
  "mcpServers": {
    "arxiv": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

Cloud and load-balancer probes should GET http://<host>:<port>/healthz. It returns 200 with body ok once the HTTP server is listening. There is no separate /ready check: if the process is up, it is ready. The stdio transport has no HTTP endpoints.

The server binds to 127.0.0.1 by default and enables MCP DNS-rebinding protection. If a reverse proxy exposes the server, keep the process on a private interface and provide authentication and network controls upstream. Use ALLOWED_HOSTS and ALLOWED_ORIGINS for the host and origin values forwarded by the proxy.

Configuration

Environment variable names are case-insensitive through Pydantic settings. --storage-path is a command-line option rather than an environment setting.

Security

Paper text and LaTeX are untrusted external content. A paper can contain text intended to manipulate an AI client into ignoring its instructions or calling unrelated tools.

• Do not treat instructions found inside a paper as trusted commands.
• Use client approval controls for shell, browser, filesystem, and messaging tools.
• Review generated summaries before taking external actions.
• Keep Streamable HTTP private unless authentication is provided upstream.

See SECURITY.md for the reporting policy and threat details.

Development

git clone https://github.com/blazickjp/arxiv-mcp-server.git
cd arxiv-mcp-server
uv sync --extra test --extra dev
uv run pytest
uv run black --check .

Run the development checkout from an MCP client with:

{
  "mcpServers": {
    "arxiv-dev": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/arxiv-mcp-server",
        "run",
        "arxiv-mcp-server"
      ]
    }
  }
}

Contributions are welcome. Read CONTRIBUTING.md before opening a pull request, and use GitHub Issues for reproducible bugs or scoped feature proposals.

License

Apache License 2.0. See LICENSE.