这是一个基于 Model Context Protocol 的本地服务器，面向需要查阅 arXiv 文献的 AI 代理。与常见的搜索封装不同，它把文献处理流程放在本地：按章节读取作者提交的原始 LaTeX 源码、从 arXiv 元数据生成 BibTeX、把主题监控记录保存在磁盘上，下载的论文也留在本地目录而不上传。服务器通过 stdio 运行，内置约 19 个工具，涵盖检索、获取摘要、下载并转成 Markdown、列出本地论文、读取章节大纲与指定段落，单次读取默认限制字符数以避免上下文过载。搜索、引用图谱等能力按需调用外部服务，属于可选项。安装只需一条 uvx 命令，也可作为 Claude Code、Codex、Kiro 等客户端的插件使用。
uvx arxiv-mcp-serverThe 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.
Per-client recipes (Claude Code, Codex, Hermes, VS Code / Kiro, Claude Desktop, plugins)
Use the default JSON above unless your client has a one-line helper.
Add the MCP server for all projects:
claude mcp add --transport stdio --scope user arxiv -- uvx arxiv-mcp-server
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:
claude plugin marketplace add blazickjp/arxiv-mcp-server
claude plugin install arxiv-mcp-server@arxiv-mcp
Verify the direct MCP installation with claude mcp get arxiv. Restart Claude Code or run /reload-plugins after installing the plugin.
Add the MCP server:
codex mcp add arxiv -- uvx arxiv-mcp-server
Or install the MCP connection and bundled research skill as a Codex plugin:
codex plugin marketplace add blazickjp/arxiv-mcp-server
codex plugin add arxiv-mcp-server@arxiv-mcp
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.
Add the server, approve the discovered tools, and test the saved connection:
hermes mcp add arxiv --command uvx --args arxiv-mcp-server
hermes mcp test arxiv
For the richer Kiro Power integration, open the Powers panel, choose Add Custom Power → Import power from GitHub, and enter:
https://github.com/blazickjp/arxiv-mcp-server
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.
macOS users can install a bundled .mcpb extension from the v0.8.2 release or the latest GitHub release:
arxiv-mcp-server-darwin-arm64-0.8.2.mcpbarxiv-mcp-server-darwin-x86_64-0.8.2.mcpbDouble-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.
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.
The same MCP server and research skill are packaged for both major plugin systems:
| Integration | Manifest | Marketplace |
|---|---|---|
| Claude Code | .claude-plugin/plugin.json | .claude-plugin/marketplace.json |
| OpenAI Codex / ChatGPT Work | .codex-plugin/plugin.json | .agents/plugins/marketplace.json |
| Kiro Power | POWER.md | mcp.json |
| Shared MCP launch | .mcp.json for Claude and repository-local clients; .codex-mcp.json for Codex plugins | uvx arxiv-mcp-server |
| Shared research workflow | skills/arxiv-mcp-server/SKILL.md | Installed with either plugin |
uvxDesktop 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.
| Tool | Purpose | Notes |
|---|---|---|
search_papers | Search arXiv by query, category, date, and sort order | Default ≤5 compact results (abstract_mode=snippet); remote arXiv API |
get_abstract | Fetch metadata and an abstract by arXiv ID | Does not download the paper |
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 |
list_papers | List papers stored locally | Returns id, title, authors, published; compact for IDs only |
read_paper | Read locally stored paper content | Bounded to 12,000 chars by default; supports start/max_chars/return_full_text |
get_paper_outline | Paginated markdown heading outline | Stable hierarchical section IDs |
read_paper_section | Read one bounded markdown section | By outline ID or unique title |
search_paper_text | Bounded passage search in a paper | Source offsets; no Torch required |
get_paper_latex | Retrieve bounded author-submitted LaTeX | Remote arXiv source archive |
list_paper_latex_sections | Return a paginated LaTeX outline | Supports start and max_sections |
get_paper_latex_section | Read one bounded LaTeX section | Select by outline ID or exact title |
citation_graph | Fetch references and citing papers | Remote Semantic Scholar API (1 call per paper, cached on disk); optional free API key improves reliability |
export_citations | Export BibTeX for one or more arXiv IDs | Authoritative arXiv metadata |
watch_topic | Save or update an arXiv topic watch | Stored locally; omit categories to preserve on update, categories: [] to clear |
list_watches | List saved topic watches | Read-only; does not advance last_checked |
check_alerts | Check saved watches for new papers | Returns papers since the last check |
unwatch_topic | Delete a saved topic watch | Exact topic match; not-found if missing |
semantic_search | Search downloaded papers by semantic similarity | Requires [pro] |
reindex | Rebuild the local semantic index | Requires [pro] |
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):
categories → preserve the stored category filters (and other fields you leave unchanged).categories: [] → clear category 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
"multi-agent systems", "neural networks""AI agents" OR "software agents"ti:"exact title phrase", au:"author name", abs:"keyword", cat:cs.LG"machine learning" ANDNOT "survey"Advanced patterns
ti:"transformer architecture"au:"Smith" AND ti:"quantum""deep learning" ANDNOT ("survey" OR "review")"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
YYYY-MM-DD (date_from / date_to)sort_by is relevance; use date for newest-first monitoringdate_to: "2010-12-31" with title/abstract field searchesResult size, abstracts, and pagination
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.total_results (corpus hits), returned, has_more, start, next_start, and abstract_modestart=next_start with the same abstract_mode for the next pageAsk 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.
| Need | Call |
|---|---|
| First bounded chunk (new default) | { "paper_id": "…" } |
| Continue reading | { "paper_id": "…", "start": } |
| Custom chunk size | { "paper_id": "…", "max_chars": 5000 } |
| Old unbounded behavior | { "paper_id": "…", "return_full_text": true } |
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.
| Prompt | Required arguments | Purpose |
|---|---|---|
research-discovery | topic | Map terminology, searches, papers, research clusters, and a reading path |
deep-paper-analysis | paper_id | Analyze one paper in depth |
summarize_paper | paper_id | Summarize methods, results, and limitations |
compare_papers | paper_ids | Compare multiple papers |
literature_review | topic | Synthesize a topic and optional paper set |
literature-synthesis | paper_ids | Synthesize themes, methods, timelines, or gaps across papers |
research-question | paper_ids, topic | Formulate grounded, falsifiable research questions |
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://:/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.
| Setting | Default | Purpose |
|---|---|---|
--storage-path | ~/.arxiv-mcp-server/papers | Paper, source-cache, alert, and index storage |
MAX_RESULTS | 50 | Server-side cap for result counts |
ARXIV_REQUEST_TIMEOUT | 30 | Per-attempt read timeout in seconds for all arXiv requests (API, HTML, PDF, LaTeX). Values ≤ 0 fall back to default. |
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. |
ARXIV_CONNECT_TIMEOUT | 10 | Connection timeout in seconds for all arXiv requests. Values ≤ 0 fall back to default. |
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. |
ARXIV_MAX_RETRIES | 2 | Maximum retry attempts for transient failures (timeouts, connections, 429, 503) |
ARXIV_HTTP_406_MAX_RETRIES | 1 | Maximum retry attempts for HTTP 406 (IP-level throttling, use minimal retries) |
ARXIV_INITIAL_BACKOFF | 2.0 | Initial exponential backoff delay in seconds |
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. |
TRANSPORT | stdio | stdio, http, or streamable-http |
HOST | 127.0.0.1 | HTTP bind host |
PORT | 8000 | HTTP bind port |
ALLOWED_HOSTS | empty | Additional accepted HTTP Host values |
ALLOWED_ORIGINS | empty | Additional accepted HTTP Origin values |
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. |
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.
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.
内容由编辑整理，部分信息来自 GitHub 与项目官网，版权归原作者所有。发现错误？报告问题