Skip to content
Back to search

arxiv-mcp-server

A local MCP server for agent literature work. Original-LaTeX section reads, BibTeX from arXiv metadata, and topic watches. Papers stay on disk. Search is optional.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/blazickjp/arxiv-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/blazickjp/arxiv-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/blazickjp--arxiv-mcp-server/badge.svg)](/listings/blazickjp--arxiv-mcp-server)

HTML

<a href="/listings/blazickjp--arxiv-mcp-server"><img src="/api/listings/blazickjp--arxiv-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The default install is `uvx arxiv-mcp-server`. Command-based integrations need [uv](https://docs.astral.sh/uv/getting-started/installation/), 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.1`. 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](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.blazickjp%2Farxiv-mcp-server/versions/latest), latest 0.8.1.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 16 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://www.schemastore.org/claude-code-marketplace.json",
  3. "name": "arxiv-mcp",
  4. "description": "Claude Code integration for searching and analyzing arXiv papers.",
  5. "owner": {
  6. "name": "Joseph Blazick"
  7. },
  8. "plugins": [
  9. {
  10. "name": "arxiv-mcp-server",
  11. "source": "./",
  12. "description": "Search, download, read, and analyze arXiv papers through MCP.",
  13. "category": "research"
  14. }
  15. ]
  16. }
README.md · README · 522 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # arxiv-mcp-server
  2. <!-- mcp-name: io.github.blazickjp/arxiv-mcp-server -->
  3. [![PyPI](https://img.shields.io/pypi/v/arxiv-mcp-server.svg)](https://pypi.org/project/arxiv-mcp-server/)
  4. [![Downloads](https://static.pepy.tech/badge/arxiv-mcp-server)](https://pypi.org/project/arxiv-mcp-server/)
  5. [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
  6. [![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed,_latest_0.8.2-5C5CFF?style=flat-square)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.blazickjp%2Farxiv-mcp-server/versions/latest)
  7. [![Tests](https://github.com/blazickjp/arxiv-mcp-server/actions/workflows/tests.yml/badge.svg)](https://github.com/blazickjp/arxiv-mcp-server/actions/workflows/tests.yml)
  8. [![GitHub stars](https://img.shields.io/github/stars/blazickjp/arxiv-mcp-server)](https://github.com/blazickjp/arxiv-mcp-server/stargazers)
  9. [![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=arxiv-mcp-server&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22arxiv-mcp-server%22%5D%7D)
  10. [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=arxiv-mcp-server&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJhcnhpdi1tY3Atc2VydmVyIl19)
  11. [![Add to Kiro](https://kiro.dev/images/add-to-kiro.svg)](https://kiro.dev/launch/mcp/add?name=arxiv-mcp-server&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22arxiv-mcp-server%22%5D%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D)
  12. [![Claude Code](https://img.shields.io/badge/Claude_Code-Install-D97757?style=flat-square&logo=anthropic&logoColor=white)](#claude-code)
  13. [![OpenAI Codex](https://img.shields.io/badge/OpenAI_Codex-Install-000000?style=flat-square&logo=openai&logoColor=white)](#openai-codex)
  14. [![Hermes Agent](https://img.shields.io/badge/Hermes_Agent-Install-6C5CE7?style=flat-square)](#hermes-agent)
  15. 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.
  16. ## Install
  17. The default install is `uvx arxiv-mcp-server`. Command-based integrations need [uv](https://docs.astral.sh/uv/getting-started/installation/), which provides `uvx`. No repository clone or Python environment setup is required.
  18. ```bash
  19. uvx arxiv-mcp-server
  20. ```
  21. 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.
  22. ```json
  23. {
  24. "mcpServers": {
  25. "arxiv": {
  26. "type": "stdio",
  27. "command": "uvx",
  28. "args": ["arxiv-mcp-server"]
  29. }
  30. }
  31. }
  32. ```
  33. The default paper directory is `~/.arxiv-mcp-server/papers`. To choose another directory, append `"--storage-path", "/absolute/path/to/papers"` to `args`.
  34. 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`.
  35. Listed on the [official MCP registry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.blazickjp%2Farxiv-mcp-server/versions/latest), latest 0.8.2.
  36. ## Why this is not a search wrapper
  37. 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.
  38. <details>
  39. <summary>Per-client recipes (Claude Code, Codex, Hermes, VS Code / Kiro, Claude Desktop, plugins)</summary>
  40. Use the default JSON above unless your client has a one-line helper.
  41. ### Claude Code
  42. Add the MCP server for all projects:
  43. ```bash
  44. claude mcp add --transport stdio --scope user arxiv -- uvx arxiv-mcp-server
  45. ```
  46. For the richer plugin integration—which installs the MCP connection plus the bundled arXiv research skill—register this repository as a marketplace and install the plugin:
  47. ```bash
  48. claude plugin marketplace add blazickjp/arxiv-mcp-server
  49. claude plugin install arxiv-mcp-server@arxiv-mcp
  50. ```
  51. Verify the direct MCP installation with `claude mcp get arxiv`. Restart Claude Code or run `/reload-plugins` after installing the plugin.
  52. ### OpenAI Codex
  53. Add the MCP server:
  54. ```bash
  55. codex mcp add arxiv -- uvx arxiv-mcp-server
  56. ```
  57. Or install the MCP connection and bundled research skill as a Codex plugin:
  58. ```bash
  59. codex plugin marketplace add blazickjp/arxiv-mcp-server
  60. codex plugin add arxiv-mcp-server@arxiv-mcp
  61. ```
  62. Verify the direct MCP installation with `codex mcp get arxiv`. Codex CLI, the Codex IDE extension, and Codex in the ChatGPT desktop app share this MCP configuration.
  63. ### Hermes Agent
  64. [![Hermes Agent](https://img.shields.io/badge/Hermes_Agent-Install-6C5CE7?style=flat-square)](#hermes-agent)
  65. Add the server, approve the discovered tools, and test the saved connection:
  66. ```bash
  67. hermes mcp add arxiv --command uvx --args arxiv-mcp-server
  68. hermes mcp test arxiv
  69. ```
  70. ### VS Code and Kiro
  71. [![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=arxiv-mcp-server&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22arxiv-mcp-server%22%5D%7D)
  72. [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=arxiv-mcp-server&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJhcnhpdi1tY3Atc2VydmVyIl19)
  73. [![Add to Kiro](https://kiro.dev/images/add-to-kiro.svg)](https://kiro.dev/launch/mcp/add?name=arxiv-mcp-server&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22arxiv-mcp-server%22%5D%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D)
  74. For the richer Kiro Power integration, open the **Powers** panel, choose **Add Custom Power → Import power from GitHub**, and enter:
  75. ```text
  76. https://github.com/blazickjp/arxiv-mcp-server
  77. ```
  78. The Power installs the MCP connection from `mcp.json` and adds focused arXiv research guidance. Kiro users who prefer manual configuration can place the generic configuration above in `.kiro/settings/mcp.json` for one workspace or `~/.kiro/settings/mcp.json` for all workspaces.
  79. ### Claude Desktop bundle
  80. macOS users can install a bundled `.mcpb` extension from the [v0.8.2 release](https://github.com/blazickjp/arxiv-mcp-server/releases/tag/v0.8.2) or the [latest GitHub release](https://github.com/blazickjp/arxiv-mcp-server/releases/latest):
  81. - Apple Silicon: [`arxiv-mcp-server-darwin-arm64-0.8.2.mcpb`](https://github.com/blazickjp/arxiv-mcp-server/releases/download/v0.8.2/arxiv-mcp-server-darwin-arm64-0.8.2.mcpb)
  82. - Intel: [`arxiv-mcp-server-darwin-x86_64-0.8.2.mcpb`](https://github.com/blazickjp/arxiv-mcp-server/releases/download/v0.8.2/arxiv-mcp-server-darwin-x86_64-0.8.2.mcpb)
  83. Double-click the bundle, drag it into Claude Desktop, or open **Settings → Extensions → Advanced settings → Install Extension…**. The bundle includes the server dependencies and requires CPython 3.11.x.
  84. ### Other MCP clients
  85. Other clients may use a top-level `servers` object, TOML, or their own settings UI; consult the client MCP documentation. Direct MCP installation is the shortest path. Install a plugin when you also want the research workflow that steers the client toward focused searches, bounded reads, citation traversal, and section-level LaTeX retrieval.
  86. ### Plugin manifests
  87. The same MCP server and research skill are packaged for both major plugin systems:
  88. | Integration | Manifest | Marketplace |
  89. |---|---|---|
  90. | Claude Code | `.claude-plugin/plugin.json` | `.claude-plugin/marketplace.json` |
  91. | OpenAI Codex / ChatGPT Work | `.codex-plugin/plugin.json` | `.agents/plugins/marketplace.json` |
  92. | Kiro Power | `POWER.md` | `mcp.json` |
  93. | Shared MCP launch | `.mcp.json` for Claude and repository-local clients; `.codex-mcp.json` for Codex plugins | `uvx arxiv-mcp-server` |
  94. | Shared research workflow | `skills/arxiv-mcp-server/SKILL.md` | Installed with either plugin |
  95. </details>
  96. ## If a desktop client cannot find `uvx`
  97. 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:
  98. ```bash
  99. # macOS and Linux
  100. command -v uvx
  101. ```
  102. ```powershell
  103. # Windows PowerShell
  104. (Get-Command uvx).Source
  105. ```
  106. Replace `"command": "uvx"` with the returned absolute path, then restart the client. Keep the `args` value unchanged.
  107. ## If an existing installation is missing newer tools
  108. `uvx` reuses cached tool environments. Force it to resolve the current PyPI release with a supported interpreter, then restart your MCP client:
  109. ```bash
  110. uvx --python 3.11 --refresh-package arxiv-mcp-server arxiv-mcp-server
  111. ```
  112. If your client still launches an older environment, add `"--python", "3.11"` before `"arxiv-mcp-server"` in its `args` array.
  113. ## Persistent command install
  114. To place `arxiv-mcp-server` on your `PATH` instead of launching it through `uvx`:
  115. ```bash
  116. uv tool install arxiv-mcp-server
  117. ```
  118. 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`.
  119. ## Tools
  120. The server currently exposes 19 tools.
  121. | Tool | Purpose | Notes |
  122. |---|---|---|
  123. | `search_papers` | Search arXiv by query, category, date, and sort order | Default ≤5 compact results (`abstract_mode=snippet`); remote arXiv API |
  124. | `get_abstract` | Fetch metadata and an abstract by arXiv ID | Does not download the paper |
  125. | `download_paper` | Download and convert a paper to local Markdown | HTML first; PDF fallback uses `[pdf]`; `force=true` re-fetches; content bounded to 12,000 chars by default |
  126. | `list_papers` | List papers stored locally | Returns id, title, authors, published; `compact` for IDs only |
  127. | `read_paper` | Read locally stored paper content | Bounded to 12,000 chars by default; supports `start`/`max_chars`/`return_full_text` |
  128. | `get_paper_outline` | Paginated markdown heading outline | Stable hierarchical section IDs |
  129. | `read_paper_section` | Read one bounded markdown section | By outline ID or unique title |
  130. | `search_paper_text` | Bounded passage search in a paper | Source offsets; no Torch required |
  131. | `get_paper_latex` | Retrieve bounded author-submitted LaTeX | Remote arXiv source archive |
  132. | `list_paper_latex_sections` | Return a paginated LaTeX outline | Supports `start` and `max_sections` |
  133. | `get_paper_latex_section` | Read one bounded LaTeX section | Select by outline ID or exact title |
  134. | `citation_graph` | Fetch references and citing papers | Remote Semantic Scholar API (1 call per paper, cached on disk); optional free API key improves reliability |
  135. | `export_citations` | Export BibTeX for one or more arXiv IDs | Authoritative arXiv metadata |
  136. | `watch_topic` | Save or update an arXiv topic watch | Stored locally; omit `categories` to preserve on update, `categories: []` to clear |
  137. | `list_watches` | List saved topic watches | Read-only; does not advance last_checked |
  138. | `check_alerts` | Check saved watches for new papers | Returns papers since the last check |
  139. | `unwatch_topic` | Delete a saved topic watch | Exact topic match; not-found if missing |
  140. | `semantic_search` | Search downloaded papers by semantic similarity | Requires `[pro]` |
  141. | `reindex` | Rebuild the local semantic index | Requires `[pro]` |
  142. ### Research alerts (`watch_topic`)
  143. Save standing topic watches with `watch_topic`, inspect them with `list_watches`, poll with `check_alerts`, and remove with `unwatch_topic`.
  144. When updating an existing watch (same `topic` string):
  145. - **Omit** `categories` → **preserve** the stored category filters (and other fields you leave unchanged).
  146. - Pass **`categories: []`** → **clear** category filters.
  147. - Pass a non-empty list → replace the stored filters.
  148. Create path: omitting `categories` stores an empty list (no category filter).
  149. ### search_papers query guide
  150. Tool schemas stay short on purpose. Use this section (not the always-loaded MCP description) for query tutorials, category catalogs, and workflow examples.
  151. **Query construction**
  152. - Use quoted phrases for exact matches: `"multi-agent systems"`, `"neural networks"`
  153. - Combine related concepts with OR: `"AI agents" OR "software agents"`
  154. - Field-specific searches: `ti:"exact title phrase"`, `au:"author name"`, `abs:"keyword"`, `cat:cs.LG`
  155. - Exclude with ANDNOT: `"machine learning" ANDNOT "survey"`
  156. - Prefer 2–4 core concepts over long keyword lists
  157. **Advanced patterns**
  158. - Field + phrase: `ti:"transformer architecture"`
  159. - Multiple fields: `au:"Smith" AND ti:"quantum"`
  160. - Exclusions: `"deep learning" ANDNOT ("survey" OR "review")`
  161. - Broad + narrow: `"artificial intelligence" AND (robotics OR "computer vision")`
  162. **Category filtering** (recommended for relevance)
  163. 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)
  164. Statistics & Math: `stat.ML`, `stat.AP`, `math.OC`, `math.ST`
  165. Physics & other: `quant-ph`, `eess.SP`, `eess.AS`, `physics.data-an`
  166. **Effective examples**
  167. - `ti:"reinforcement learning"` with `categories: ["cs.LG", "cs.AI"]`
  168. - `au:"Hinton" AND "deep learning"` with `categories: ["cs.LG"]`
  169. - `"multi-agent" ANDNOT "survey"` with `categories: ["cs.MA"]`
  170. - `abs:"transformer" AND ti:"attention"` with `categories: ["cs.CL"]`
  171. **Dates and sorting**
  172. - Dates use `YYYY-MM-DD` (`date_from` / `date_to`)
  173. - Default `sort_by` is `relevance`; use `date` for newest-first monitoring
  174. - Foundational work: `date_to: "2010-12-31"` with title/abstract field searches
  175. **Result size, abstracts, and pagination**
  176. - Default `max_results` is **5** (cap 50). Pass an explicit value for larger pages.
  177. - `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.
  178. - Responses report `total_results` (corpus hits), `returned`, `has_more`, `start`, `next_start`, and `abstract_mode`
  179. - Pass `start=next_start` with the same `abstract_mode` for the next page
  180. - arXiv enforces ~3 seconds between requests (handled server-side); on rate-limit errors wait ~60s
  181. ### Search and inspect a paper
  182. Ask your MCP client to call `search_papers` with:
  183. ```json
  184. {
  185. "query": "\"Kolmogorov-Arnold Networks\"",
  186. "categories": ["cs.LG", "cs.AI"],
  187. "sort_by": "date"
  188. }
  189. ```
  190. 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:
  191. ```json
  192. {
  193. "paper_id": "2404.19756"
  194. }
  195. ```
  196. Do not call `get_abstract` again for papers already returned with `abstract_mode=full`.
  197. ### Download and read full text
  198. Call `download_paper` with:
  199. ```json
  200. {
  201. "paper_id": "2404.19756"
  202. }
  203. ```
  204. 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).
  205. Then page through the cached content with `read_paper`:
  206. ```json
  207. {
  208. "paper_id": "2404.19756",
  209. "start": 0
  210. }
  211. ```
  212. Or continue from a prior chunk:
  213. ```json
  214. {
  215. "paper_id": "2404.19756",
  216. "start": 12000
  217. }
  218. ```
  219. 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.
  220. #### Migration notes (bounded content default)
  221. 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.
  222. | Need | Call |
  223. |---|---|
  224. | First bounded chunk (new default) | `{ "paper_id": "…" }` |
  225. | Continue reading | `{ "paper_id": "…", "start": <next_start> }` |
  226. | Custom chunk size | `{ "paper_id": "…", "max_chars": 5000 }` |
  227. | Old unbounded behavior | `{ "paper_id": "…", "return_full_text": true }` |
  228. 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`.
  229. ### Read original LaTeX by section
  230. Call `get_paper_latex` with:
  231. ```json
  232. {
  233. "paper_id": "1706.03762"
  234. }
  235. ```
  236. Get the first page of its section outline with `list_paper_latex_sections`:
  237. ```json
  238. {
  239. "paper_id": "1706.03762",
  240. "start": 0,
  241. "max_sections": 100
  242. }
  243. ```
  244. Then call `get_paper_latex_section` using an ID from that outline:
  245. ```json
  246. {
  247. "paper_id": "1706.03762",
  248. "section_id": "3.2",
  249. "max_chars": 12000
  250. }
  251. ```
  252. LaTeX archives are validated, size-limited, and cached locally before content is returned.
  253. ## Optional dependencies
  254. Choose the install variant that matches the features you need:
  255. ```bash
  256. # Base server
  257. uv tool install arxiv-mcp-server
  258. # Base server plus PDF conversion
  259. uv tool install "arxiv-mcp-server[pdf]"
  260. # Base server plus local semantic search
  261. uv tool install "arxiv-mcp-server[pro]"
  262. ```
  263. If the base tool is already installed, reinstall the selected variant:
  264. ```bash
  265. uv tool install --force "arxiv-mcp-server[pdf]"
  266. ```
  267. 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.
  268. For older papers that require PDF conversion, run the package with its PDF extra:
  269. ```json
  270. {
  271. "mcpServers": {
  272. "arxiv": {
  273. "type": "stdio",
  274. "command": "uvx",
  275. "args": [
  276. "--from",
  277. "arxiv-mcp-server[pdf]",
  278. "arxiv-mcp-server"
  279. ]
  280. }
  281. }
  282. }
  283. ```
  284. ## Built-in prompts
  285. 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.
  286. | Prompt | Required arguments | Purpose |
  287. |---|---|---|
  288. | `research-discovery` | `topic` | Map terminology, searches, papers, research clusters, and a reading path |
  289. | `deep-paper-analysis` | `paper_id` | Analyze one paper in depth |
  290. | `summarize_paper` | `paper_id` | Summarize methods, results, and limitations |
  291. | `compare_papers` | `paper_ids` | Compare multiple papers |
  292. | `literature_review` | `topic` | Synthesize a topic and optional paper set |
  293. | `literature-synthesis` | `paper_ids` | Synthesize themes, methods, timelines, or gaps across papers |
  294. | `research-question` | `paper_ids`, `topic` | Formulate grounded, falsifiable research questions |
  295. ## Streamable HTTP
  296. For deployments where stdio is not practical:
  297. ```bash
  298. TRANSPORT=http HOST=127.0.0.1 PORT=8080 \
  299. uvx arxiv-mcp-server --storage-path /absolute/path/to/papers
  300. ```
  301. PowerShell:
  302. ```powershell
  303. $env:TRANSPORT = "http"
  304. $env:HOST = "127.0.0.1"
  305. $env:PORT = "8080"
  306. uvx arxiv-mcp-server --storage-path C:\absolute\path\to\papers
  307. ```
  308. Connect clients to:
  309. ```json
  310. {
  311. "mcpServers": {
  312. "arxiv": {
  313. "type": "http",
  314. "url": "http://127.0.0.1:8080/mcp"
  315. }
  316. }
  317. }
  318. ```
  319. 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.
  320. 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.
  321. ## Configuration
  322. | Setting | Default | Purpose |
  323. |---|---:|---|
  324. | `--storage-path` | `~/.arxiv-mcp-server/papers` | Paper, source-cache, alert, and index storage |
  325. | `MAX_RESULTS` | `50` | Server-side cap for result counts |
  326. | `ARXIV_REQUEST_TIMEOUT` | `30` | Per-attempt read timeout in seconds for all arXiv requests (API, HTML, PDF, LaTeX). Values ≤ 0 fall back to default. |
  327. | `REQUEST_TIMEOUT` | – | **Deprecated.** Legacy alias for `ARXIV_REQUEST_TIMEOUT` (applies to all requests). Only used when `ARXIV_REQUEST_TIMEOUT` is not set. Effective default: 30s. Values ≤ 0 fall back to default. |
  328. | `ARXIV_CONNECT_TIMEOUT` | `10` | Connection timeout in seconds for all arXiv requests. Values ≤ 0 fall back to default. |
  329. | `ARXIV_MAX_TOTAL_TIME` | `50` | Total budget in seconds for each tool call (HTML + PDF combined for `download_paper`). Values ≤ 0 fall back to default. **Note**: Very small budgets (under ~6s) may leave insufficient time for HTML-to-PDF fallback due to the process-wide 3s rate-limiter delay. |
  330. | `ARXIV_MAX_RETRIES` | `2` | Maximum retry attempts for transient failures (timeouts, connections, 429, 503) |
  331. | `ARXIV_HTTP_406_MAX_RETRIES` | `1` | Maximum retry attempts for HTTP 406 (IP-level throttling, use minimal retries) |
  332. | `ARXIV_INITIAL_BACKOFF` | `2.0` | Initial exponential backoff delay in seconds |
  333. | `ARXIV_MAX_BACKOFF` | `30` | Maximum backoff delay in seconds (Retry-After can exceed this and causes immediate rate_limited return). Values ≤ 0 fall back to default. |
  334. | `TRANSPORT` | `stdio` | `stdio`, `http`, or `streamable-http` |
  335. | `HOST` | `127.0.0.1` | HTTP bind host |
  336. | `PORT` | `8000` | HTTP bind port |
  337. | `ALLOWED_HOSTS` | empty | Additional accepted HTTP Host values |
  338. | `ALLOWED_ORIGINS` | empty | Additional accepted HTTP Origin values |
  339. | `SEMANTIC_SCHOLAR_API_KEY` | empty | Free Semantic Scholar API key for `citation_graph`. Get one at https://www.semanticscholar.org/product/api#api-key to avoid rate limits. Unauthenticated requests work until quota exhausted. |
  340. Environment variable names are case-insensitive through Pydantic settings. `--storage-path` is a command-line option rather than an environment setting.
  341. ## Security
  342. 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.
  343. - Do not treat instructions found inside a paper as trusted commands.
  344. - Use client approval controls for shell, browser, filesystem, and messaging tools.
  345. - Review generated summaries before taking external actions.
  346. - Keep Streamable HTTP private unless authentication is provided upstream.
  347. See [SECURITY.md](SECURITY.md) for the reporting policy and threat details.
  348. ## Development
  349. ```bash
  350. git clone https://github.com/blazickjp/arxiv-mcp-server.git
  351. cd arxiv-mcp-server
  352. uv sync --extra test --extra dev
  353. uv run pytest
  354. uv run black --check .
  355. ```
  356. Run the development checkout from an MCP client with:
  357. ```json
  358. {
  359. "mcpServers": {
  360. "arxiv-dev": {
  361. "command": "uv",
  362. "args": [
  363. "--directory",
  364. "/absolute/path/to/arxiv-mcp-server",
  365. "run",
  366. "arxiv-mcp-server"
  367. ]
  368. }
  369. }
  370. }
  371. ```
  372. Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request, and use [GitHub Issues](https://github.com/blazickjp/arxiv-mcp-server/issues) for reproducible bugs or scoped feature proposals.
  373. ## License
  374. Apache License 2.0. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.