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.

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.

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

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.

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.

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.

The server currently exposes 19 tools.

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).

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

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.

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.

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.

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.

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"
      ]
    }
  }
}

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.

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.

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

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.

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.

Apache License 2.0. See LICENSE.