blazickjp/arxiv-mcp-server

arxiv‑mcp‑server – A local MCP tool for reading and organising arXiv papers

What it is – A tiny Python‑based server that talks the Model Context Protocol (MCP). It runs locally (via uvx or as a regular command) and exposes a set of “tools” that let an AI‑assistant / agent search arXiv, download papers, read them section‑by‑section (both the rendered Markdown version and the original LaTeX), keep BibTeX citations, and set up topic watches that alert you when new papers appear. The server does not host any model; it only supplies data to a client that already has a language model.

Key capabilities

Feature	How you use it	What you get
Search arXiv (search_papers)	Provide a query, optional categories, date range, sorting	Up to 5 compact results (title, authors, snippet) – can paginate and request full abstracts
Download & read (download_paper, read_paper)	Give an arXiv ID; the server fetches HTML → Markdown (PDF fallback) and stores it locally	A bounded chunk of the paper (default 12 000 characters) plus pagination info. Full‑text can be requested explicitly.
Section‑level access (get_paper_outline, read_paper_section)	First ask for an outline, then request a specific heading ID	Precise markdown of a single section, useful for step‑by‑step analysis
Original LaTeX (get_paper_latex, list_paper_latex_sections, get_paper_latex_section)	Same flow as markdown but pulls the author‑submitted LaTeX source	Bounded LaTeX snippets, handy when you need the exact equations or macros
Citation handling (citation_graph, export_citations)	Query a paper’s references and citing works (Semantic Scholar) or export BibTeX	A small citation graph and ready‑to‑paste BibTeX entries
Topic watches (watch_topic, check_alerts, …)	Save a keyword + optional arXiv categories; the server records the last‑checked timestamp	When you call check_alerts you receive any new papers that match the watch
Semantic search (semantic_search, reindex) – pro extra	After downloading papers, run a local embedding index to search by meaning	Finds similar papers without contacting arXiv; requires the optional pro extra

How you run it

• Quickest – uvx arxiv-mcp-server. uvx creates an isolated environment, downloads the package from PyPI (arxiv-mcp-server==0.8.2), and starts the server on stdio.
• Persistently on PATH – uv tool install arxiv-mcp-server (or add the [pdf] / [pro] extras).
• HTTP mode – set TRANSPORT=http and HOST/PORT env vars; clients then talk to http://host:port/mcp.

Client integration The README ships ready‑made JSON snippets for a variety of MCP‑aware tools (Claude Code, OpenAI Codex, Hermes Agent, VS Code/Kiro, Claude Desktop). The snippet tells the client to launch the server with uvx (or the installed binary) and optionally points to a custom storage directory (~/.arxiv-mcp-server/papers by default).

Why it’s not just a search wrapper The server does not perform the heavy‑lifting of searching or citation‑graph building; those calls go to the official arXiv API, Semantic Scholar, etc. What stays on your machine is the literature loop – downloading the paper, keeping a local markdown/LaTeX copy, extracting outlines, and managing watches. This keeps the data that an LLM will actually see under your control and avoids repeatedly pulling large PDFs into the model’s context.

Who would benefit

• Researchers or students who use an LLM‑assistant to explore a new topic and want the assistant to fetch real papers on‑demand.
• Developers building custom AI agents that need a reliable, local source of scholarly content without building their own arXiv scraper.
• Anyone who wants reproducible citation data (BibTeX) and the ability to read LaTeX sections directly from the source.

Installation pitfalls

• The package is published on PyPI only; an unrelated npm package with the same name exists – don’t install with npm.
• On macOS/Windows GUI apps the PATH may differ from your terminal; you may need to replace `