{
"markdown": "# arxiv-mcp-server\n\n\n\n[](https://pypi.org/project/arxiv-mcp-server/)\n[](https://pypi.org/project/arxiv-mcp-server/)\n[](LICENSE)\n[](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.blazickjp%2Farxiv-mcp-server/versions/latest)\n[](https://github.com/blazickjp/arxiv-mcp-server/actions/workflows/tests.yml)\n[](https://github.com/blazickjp/arxiv-mcp-server/stargazers)\n\n[](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)\n[](https://cursor.com/en/install-mcp?name=arxiv-mcp-server&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJhcnhpdi1tY3Atc2VydmVyIl19)\n[](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)\n[](#claude-code)\n[](#openai-codex)\n[](#hermes-agent)\n\nA 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.\n\n## Install\n\nThe 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.\n\n```bash\nuvx arxiv-mcp-server\n```\n\nAdd 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.\n\n```json\n{\n \"mcpServers\": {\n \"arxiv\": {\n \"type\": \"stdio\",\n \"command\": \"uvx\",\n \"args\": [\"arxiv-mcp-server\"]\n }\n }\n}\n```\n\nThe default paper directory is `~/.arxiv-mcp-server/papers`. To choose another directory, append `\"--storage-path\", \"/absolute/path/to/papers\"` to `args`.\n\nThe supported package is published on PyPI as `arxiv-mcp-server==0.7.2`. An unrelated npm package uses the same name, so do not install this server with npm, pnpm, or `npx arxiv-mcp-server`.\n\nListed on the [official MCP registry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.blazickjp%2Farxiv-mcp-server/versions/latest), latest 0.7.2.\n\n## Why this is not a search wrapper\n\nSearch, 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.\n\n\nPer-client recipes (Claude Code, Codex, Hermes, VS Code / Kiro, Claude Desktop, plugins)
\n\nUse the default JSON above unless your client has a one-line helper.\n\n### Claude Code\n\nAdd the MCP server for all projects:\n\n```bash\nclaude mcp add --transport stdio --scope user arxiv -- uvx arxiv-mcp-server\n```\n\nFor 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:\n\n```bash\nclaude plugin marketplace add blazickjp/arxiv-mcp-server\nclaude plugin install arxiv-mcp-server@arxiv-mcp\n```\n\nVerify the direct MCP installation with `claude mcp get arxiv`. Restart Claude Code or run `/reload-plugins` after installing the plugin.\n\n### OpenAI Codex\n\nAdd the MCP server:\n\n```bash\ncodex mcp add arxiv -- uvx arxiv-mcp-server\n```\n\nOr install the MCP connection and bundled research skill as a Codex plugin:\n\n```bash\ncodex plugin marketplace add blazickjp/arxiv-mcp-server\ncodex plugin add arxiv-mcp-server@arxiv-mcp\n```\n\nVerify 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.\n\n### Hermes Agent\n\n[](#hermes-agent)\n\nAdd the server, approve the discovered tools, and test the saved connection:\n\n```bash\nhermes mcp add arxiv --command uvx --args arxiv-mcp-server\nhermes mcp test arxiv\n```\n\n### VS Code and Kiro\n\n[](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)\n[](https://cursor.com/en/install-mcp?name=arxiv-mcp-server&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJhcnhpdi1tY3Atc2VydmVyIl19)\n[](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)\n\nFor the richer Kiro Power integration, open the **Powers** panel, choose **Add Custom Power → Import power from GitHub**, and enter:\n\n```text\nhttps://github.com/blazickjp/arxiv-mcp-server\n```\n\nThe 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.\n\n### Claude Desktop bundle\n\nmacOS users can install a bundled `.mcpb` extension from the [v0.7.2 release](https://github.com/blazickjp/arxiv-mcp-server/releases/tag/v0.7.2) or the [latest GitHub release](https://github.com/blazickjp/arxiv-mcp-server/releases/latest):\n\n- Apple Silicon: [`arxiv-mcp-server-darwin-arm64-0.7.2.mcpb`](https://github.com/blazickjp/arxiv-mcp-server/releases/download/v0.7.2/arxiv-mcp-server-darwin-arm64-0.7.2.mcpb)\n- Intel: [`arxiv-mcp-server-darwin-x86_64-0.7.2.mcpb`](https://github.com/blazickjp/arxiv-mcp-server/releases/download/v0.7.2/arxiv-mcp-server-darwin-x86_64-0.7.2.mcpb)\n\nDouble-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.\n\n### Other MCP clients\n\nOther 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.\n\n### Plugin manifests\n\nThe same MCP server and research skill are packaged for both major plugin systems:\n\n| Integration | Manifest | Marketplace |\n|---|---|---|\n| Claude Code | `.claude-plugin/plugin.json` | `.claude-plugin/marketplace.json` |\n| OpenAI Codex / ChatGPT Work | `.codex-plugin/plugin.json` | `.agents/plugins/marketplace.json` |\n| Kiro Power | `POWER.md` | `mcp.json` |\n| Shared MCP launch | `.mcp.json` for Claude and repository-local clients; `.codex-mcp.json` for Codex plugins | `uvx arxiv-mcp-server` |\n| Shared research workflow | `skills/arxiv-mcp-server/SKILL.md` | Installed with either plugin |\n\n \n\n## If a desktop client cannot find `uvx`\n\nDesktop 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:\n\n```bash\n# macOS and Linux\ncommand -v uvx\n```\n\n```powershell\n# Windows PowerShell\n(Get-Command uvx).Source\n```\n\nReplace `\"command\": \"uvx\"` with the returned absolute path, then restart the client. Keep the `args` value unchanged.\n\n## If an existing installation is missing newer tools\n\n`uvx` reuses cached tool environments. Force it to resolve the current PyPI release with a supported interpreter, then restart your MCP client:\n\n```bash\nuvx --python 3.11 --refresh-package arxiv-mcp-server arxiv-mcp-server\n```\n\nIf your client still launches an older environment, add `\"--python\", \"3.11\"` before `\"arxiv-mcp-server\"` in its `args` array.\n\n## Persistent command install\n\nTo place `arxiv-mcp-server` on your `PATH` instead of launching it through `uvx`:\n\n```bash\nuv tool install arxiv-mcp-server\n```\n\nIf 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`.\n\n## Tools\n\nThe server currently exposes 19 tools.\n\n| Tool | Purpose | Notes |\n|---|---|---|\n| `search_papers` | Search arXiv by query, category, date, and sort order | Default ≤5 compact results (`abstract_mode=snippet`); remote arXiv API |\n| `get_abstract` | Fetch metadata and an abstract by arXiv ID | Does not download the paper |\n| `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 |\n| `list_papers` | List papers stored locally | Returns id, title, authors, published; `compact` for IDs only |\n| `read_paper` | Read locally stored paper content | Bounded to 12,000 chars by default; supports `start`/`max_chars`/`return_full_text` |\n| `get_paper_outline` | Paginated markdown heading outline | Stable hierarchical section IDs |\n| `read_paper_section` | Read one bounded markdown section | By outline ID or unique title |\n| `search_paper_text` | Bounded passage search in a paper | Source offsets; no Torch required |\n| `get_paper_latex` | Retrieve bounded author-submitted LaTeX | Remote arXiv source archive |\n| `list_paper_latex_sections` | Return a paginated LaTeX outline | Supports `start` and `max_sections` |\n| `get_paper_latex_section` | Read one bounded LaTeX section | Select by outline ID or exact title |\n| `citation_graph` | Fetch references and citing papers | Remote Semantic Scholar API (1 call per paper, cached on disk); optional free API key improves reliability |\n| `export_citations` | Export BibTeX for one or more arXiv IDs | Authoritative arXiv metadata |\n| `watch_topic` | Save or update an arXiv topic watch | Stored locally; omit `categories` to preserve on update, `categories: []` to clear |\n| `list_watches` | List saved topic watches | Read-only; does not advance last_checked |\n| `check_alerts` | Check saved watches for new papers | Returns papers since the last check |\n| `unwatch_topic` | Delete a saved topic watch | Exact topic match; not-found if missing |\n| `semantic_search` | Search downloaded papers by semantic similarity | Requires `[pro]` |\n| `reindex` | Rebuild the local semantic index | Requires `[pro]` |\n\n### Research alerts (`watch_topic`)\n\nSave standing topic watches with `watch_topic`, inspect them with `list_watches`, poll with `check_alerts`, and remove with `unwatch_topic`.\n\nWhen updating an existing watch (same `topic` string):\n\n- **Omit** `categories` → **preserve** the stored category filters (and other fields you leave unchanged).\n- Pass **`categories: []`** → **clear** category filters.\n- Pass a non-empty list → replace the stored filters.\n\nCreate path: omitting `categories` stores an empty list (no category filter).\n\n### search_papers query guide\n\nTool schemas stay short on purpose. Use this section (not the always-loaded MCP description) for query tutorials, category catalogs, and workflow examples.\n\n**Query construction**\n\n- Use quoted phrases for exact matches: `\"multi-agent systems\"`, `\"neural networks\"`\n- Combine related concepts with OR: `\"AI agents\" OR \"software agents\"`\n- Field-specific searches: `ti:\"exact title phrase\"`, `au:\"author name\"`, `abs:\"keyword\"`, `cat:cs.LG`\n- Exclude with ANDNOT: `\"machine learning\" ANDNOT \"survey\"`\n- Prefer 2–4 core concepts over long keyword lists\n\n**Advanced patterns**\n\n- Field + phrase: `ti:\"transformer architecture\"`\n- Multiple fields: `au:\"Smith\" AND ti:\"quantum\"`\n- Exclusions: `\"deep learning\" ANDNOT (\"survey\" OR \"review\")`\n- Broad + narrow: `\"artificial intelligence\" AND (robotics OR \"computer vision\")`\n\n**Category filtering** (recommended for relevance)\n\nComputer 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)\n\nStatistics & Math: `stat.ML`, `stat.AP`, `math.OC`, `math.ST`\n\nPhysics & other: `quant-ph`, `eess.SP`, `eess.AS`, `physics.data-an`\n\n**Effective examples**\n\n- `ti:\"reinforcement learning\"` with `categories: [\"cs.LG\", \"cs.AI\"]`\n- `au:\"Hinton\" AND \"deep learning\"` with `categories: [\"cs.LG\"]`\n- `\"multi-agent\" ANDNOT \"survey\"` with `categories: [\"cs.MA\"]`\n- `abs:\"transformer\" AND ti:\"attention\"` with `categories: [\"cs.CL\"]`\n\n**Dates and sorting**\n\n- Dates use `YYYY-MM-DD` (`date_from` / `date_to`)\n- Default `sort_by` is `relevance`; use `date` for newest-first monitoring\n- Foundational work: `date_to: \"2010-12-31\"` with title/abstract field searches\n\n**Result size, abstracts, and pagination**\n\n- Default `max_results` is **5** (cap 50). Pass an explicit value for larger pages.\n- `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.\n- Responses report `total_results` (corpus hits), `returned`, `has_more`, `start`, `next_start`, and `abstract_mode`\n- Pass `start=next_start` with the same `abstract_mode` for the next page\n- arXiv enforces ~3 seconds between requests (handled server-side); on rate-limit errors wait ~60s\n\n### Search and inspect a paper\n\nAsk your MCP client to call `search_papers` with:\n\n```json\n{\n \"query\": \"\\\"Kolmogorov-Arnold Networks\\\"\",\n \"categories\": [\"cs.LG\", \"cs.AI\"],\n \"sort_by\": \"date\"\n}\n```\n\nDefaults 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:\n\n```json\n{\n \"paper_id\": \"2404.19756\"\n}\n```\n\nDo not call `get_abstract` again for papers already returned with `abstract_mode=full`.\n\n### Download and read full text\n\nCall `download_paper` with:\n\n```json\n{\n \"paper_id\": \"2404.19756\"\n}\n```\n\nOmitting `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).\n\nThen page through the cached content with `read_paper`:\n\n```json\n{\n \"paper_id\": \"2404.19756\",\n \"start\": 0\n}\n```\n\nOr continue from a prior chunk:\n\n```json\n{\n \"paper_id\": \"2404.19756\",\n \"start\": 12000\n}\n```\n\nLarge-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.\n\n#### Migration notes (bounded content default)\n\nPreviously, 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.\n\n| Need | Call |\n|---|---|\n| First bounded chunk (new default) | `{ \"paper_id\": \"…\" }` |\n| Continue reading | `{ \"paper_id\": \"…\", \"start\": }` |\n| Custom chunk size | `{ \"paper_id\": \"…\", \"max_chars\": 5000 }` |\n| Old unbounded behavior | `{ \"paper_id\": \"…\", \"return_full_text\": true }` |\n\nClients 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`.\n\n### Read original LaTeX by section\n\nCall `get_paper_latex` with:\n\n```json\n{\n \"paper_id\": \"1706.03762\"\n}\n```\n\nGet the first page of its section outline with `list_paper_latex_sections`:\n\n```json\n{\n \"paper_id\": \"1706.03762\",\n \"start\": 0,\n \"max_sections\": 100\n}\n```\n\nThen call `get_paper_latex_section` using an ID from that outline:\n\n```json\n{\n \"paper_id\": \"1706.03762\",\n \"section_id\": \"3.2\",\n \"max_chars\": 12000\n}\n```\n\nLaTeX archives are validated, size-limited, and cached locally before content is returned.\n\n## Optional dependencies\n\nChoose the install variant that matches the features you need:\n\n```bash\n# Base server\nuv tool install arxiv-mcp-server\n\n# Base server plus PDF conversion\nuv tool install \"arxiv-mcp-server[pdf]\"\n\n# Base server plus local semantic search\nuv tool install \"arxiv-mcp-server[pro]\"\n```\n\nIf the base tool is already installed, reinstall the selected variant:\n\n```bash\nuv tool install --force \"arxiv-mcp-server[pdf]\"\n```\n\nThe `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.\n\nFor older papers that require PDF conversion, run the package with its PDF extra:\n\n```json\n{\n \"mcpServers\": {\n \"arxiv\": {\n \"type\": \"stdio\",\n \"command\": \"uvx\",\n \"args\": [\n \"--from\",\n \"arxiv-mcp-server[pdf]\",\n \"arxiv-mcp-server\"\n ]\n }\n }\n}\n```\n\n## Built-in prompts\n\nThe server provides seven MCP prompt workflows. Prompt availability depends on the client; the server provides workflow instructions but does not run a separate model.\n\n| Prompt | Required arguments | Purpose |\n|---|---|---|\n| `research-discovery` | `topic` | Map terminology, searches, papers, research clusters, and a reading path |\n| `deep-paper-analysis` | `paper_id` | Analyze one paper in depth |\n| `summarize_paper` | `paper_id` | Summarize methods, results, and limitations |\n| `compare_papers` | `paper_ids` | Compare multiple papers |\n| `literature_review` | `topic` | Synthesize a topic and optional paper set |\n| `literature-synthesis` | `paper_ids` | Synthesize themes, methods, timelines, or gaps across papers |\n| `research-question` | `paper_ids`, `topic` | Formulate grounded, falsifiable research questions |\n\n## Streamable HTTP\n\nFor deployments where stdio is not practical:\n\n```bash\nTRANSPORT=http HOST=127.0.0.1 PORT=8080 \\\n uvx arxiv-mcp-server --storage-path /absolute/path/to/papers\n```\n\nPowerShell:\n\n```powershell\n$env:TRANSPORT = \"http\"\n$env:HOST = \"127.0.0.1\"\n$env:PORT = \"8080\"\nuvx arxiv-mcp-server --storage-path C:\\absolute\\path\\to\\papers\n```\n\nConnect clients to:\n\n```json\n{\n \"mcpServers\": {\n \"arxiv\": {\n \"type\": \"http\",\n \"url\": \"http://127.0.0.1:8080/mcp\"\n }\n }\n}\n```\n\nCloud and load-balancer probes should GET `http://:/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.\n\nThe 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.\n\n## Configuration\n\n| Setting | Default | Purpose |\n|---|---:|---|\n| `--storage-path` | `~/.arxiv-mcp-server/papers` | Paper, source-cache, alert, and index storage |\n| `MAX_RESULTS` | `50` | Server-side cap for result counts |\n| `REQUEST_TIMEOUT` | `60` | PDF fallback download timeout in seconds |\n| `TRANSPORT` | `stdio` | `stdio`, `http`, or `streamable-http` |\n| `HOST` | `127.0.0.1` | HTTP bind host |\n| `PORT` | `8000` | HTTP bind port |\n| `ALLOWED_HOSTS` | empty | Additional accepted HTTP Host values |\n| `ALLOWED_ORIGINS` | empty | Additional accepted HTTP Origin values |\n| `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. |\n\nEnvironment variable names are case-insensitive through Pydantic settings. `--storage-path` is a command-line option rather than an environment setting.\n\n## Security\n\nPaper 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.\n\n- Do not treat instructions found inside a paper as trusted commands.\n- Use client approval controls for shell, browser, filesystem, and messaging tools.\n- Review generated summaries before taking external actions.\n- Keep Streamable HTTP private unless authentication is provided upstream.\n\nSee [SECURITY.md](SECURITY.md) for the reporting policy and threat details.\n\n## Development\n\n```bash\ngit clone https://github.com/blazickjp/arxiv-mcp-server.git\ncd arxiv-mcp-server\nuv sync --extra test --extra dev\nuv run pytest\nuv run black --check .\n```\n\nRun the development checkout from an MCP client with:\n\n```json\n{\n \"mcpServers\": {\n \"arxiv-dev\": {\n \"command\": \"uv\",\n \"args\": [\n \"--directory\",\n \"/absolute/path/to/arxiv-mcp-server\",\n \"run\",\n \"arxiv-mcp-server\"\n ]\n }\n }\n}\n```\n\nContributions 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.\n\n## License\n\nApache License 2.0. See [LICENSE](LICENSE).\n\n",
"bytes": 22834,
"sha": "438a92cea968575e9c172c042958a7dd6c6b4655e4bd0ef37171d7e0a98f5871",
"repo_slug": "blazickjp/arxiv-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_blazickjp_arxiv_mcp_server_358ab6b6/readme"
}