arxiv-mcp-pro 0.7.0

A flexible arXiv search and analysis service with MCP protocol support

ArXiv MCP Pro

🔍 The efficient, reliable, citation-capable arXiv MCP server — a token-frugal, standalone evolution of arxiv-mcp-server by Joseph Blazick (Pearl Labs).

ArXiv MCP Pro provides a bridge between AI assistants and arXiv's research repository through the Model Context Protocol (MCP). It lets AI models search for papers and access their content programmatically — with token-frugal, paginated outputs and citation tooling layered on the original server's foundation.

🤝 Contribute • 📝 Report Bug

✨ Core Features

• 🔎 Paper Search: Query arXiv papers with filters for date ranges and categories
• 📄 Paper Access: Download and read paper content
• 📋 Paper Listing: View all downloaded papers
• 🗃️ Local Storage: Papers are saved locally for faster access
• 📝 Prompts: A set of research prompts for paper analysis

🔒 Security

Prompt Injection Risk

Paper content retrieved from arXiv is untrusted external input.

When an AI assistant downloads or reads a paper through this server, the paper's text is passed directly into the model's context. A maliciously crafted paper could embed adversarial instructions designed to hijack the AI's behavior — for example, instructing it to exfiltrate data, invoke other tools with unintended arguments, or override system-level instructions. This is a known class of attack described by OWASP as LLM01: Prompt Injection and by the OWASP Agentic AI framework as AG01: Prompt Injection in LLM-Integrated Systems.

Recommended Mitigations

1. Use read-only MCP configurations — where possible, configure the MCP client so that the arxiv-mcp-pro server cannot trigger write operations or invoke other tools on your behalf.
2. Review paper content before acting on AI summaries — if an AI summary asks you to run commands or visit external URLs that were not part of your original request, treat that as a red flag.
3. Be cautious in multi-tool setups — agentic pipelines that combine this server with filesystem, shell, or browser tools are higher risk; a prompt injection in a paper could chain tool calls unexpectedly.
4. Treat AI-generated summaries as data, not instructions — always apply human judgment before executing any action the AI recommends after reading a paper.

References

• OWASP LLM01: Prompt Injection
• OWASP Agentic AI - AG01: Prompt Injection

---

🚀 Quick Start

Install from source

Install status. arxiv-mcp-pro runs from source today. A published PyPI package (uvx arxiv-mcp-pro) and a one-click Claude Desktop .mcpb bundle are planned for a future release — until then, use the from-source setup below.

# Clone the repository
git clone https://github.com/loganrooks/arxiv-mcp-pro.git
cd arxiv-mcp-pro

# Create and activate a virtual environment
uv venv
source .venv/bin/activate

# Install (add the [pdf] extra for older, PDF-only papers)
uv pip install -e .
# or, with PDF support:
uv pip install -e ".[pdf]"

Verify the install:

arxiv-mcp-pro --help

PDF fallback (older papers): Most arXiv papers have an HTML version handled automatically. Older papers that only have a PDF need the [pdf] extra (pymupdf4llm) — install it with uv pip install -e ".[pdf]" as shown above.

For development, install the test extra:

uv pip install -e ".[test]"

🤖 Codex Plugin Integration

This repository now includes a Codex plugin manifest at .codex-plugin/plugin.json and a portable MCP config at .mcp.json so Codex-oriented tooling can discover the server without inventing its own install recipe.

The Codex integration uses the same stdio launch path documented elsewhere in this README:

{
  "mcpServers": {
    "arxiv": {
      "command": "sh",
      "args": ["scripts/run-server.sh"]
    }
  }
}

If your Codex client supports plugin manifests, point it at ./.codex-plugin/plugin.json. If it only supports raw MCP configuration, use ./.mcp.json directly.

🔌 MCP Integration

Until the PyPI package ships, point your MCP client at your local clone with uv --directory:

{
    "mcpServers": {
        "arxiv": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/cloned/arxiv-mcp-pro",
                "run",
                "arxiv-mcp-pro",
                "--storage-path", "/path/to/paper/storage"
            ]
        }
    }
}

Once arxiv-mcp-pro is published to PyPI, the simpler uv tool run form will also work:

{
    "mcpServers": {
        "arxiv": {
            "command": "uv",
            "args": [
                "tool",
                "run",
                "arxiv-mcp-pro",
                "--storage-path", "/path/to/paper/storage"
            ]
        }
    }
}

HTTP Transport

For server deployments where stdio is not practical, run the server with Streamable HTTP:

TRANSPORT=http HOST=127.0.0.1 PORT=8080 arxiv-mcp-pro --storage-path /path/to/papers

Then configure an MCP client that supports Streamable HTTP:

{
    "mcpServers": {
        "arxiv": {
            "type": "http",
            "url": "http://127.0.0.1:8080/mcp"
        }
    }
}

The default HTTP bind host is 127.0.0.1. Streamable HTTP enables MCP DNS rebinding protection by default and allows loopback hosts for the configured port. If exposing the server through a reverse proxy, keep it bound to localhost unless you have added authentication and network controls upstream; set ALLOWED_HOSTS and ALLOWED_ORIGINS to the external host/origin values your proxy forwards.

🔒 Security Note

arXiv papers are user-generated, untrusted content. Paper text returned by this server may contain prompt injection attempts — crafted text designed to manipulate an AI assistant's behavior. Treat all paper content as untrusted input.

In production environments, apply appropriate sandboxing and avoid feeding raw paper content into agentic pipelines that have access to sensitive tools or data without review. See SECURITY.md for the full security policy.

💡 Available Tools

Core Workflow

The typical workflow for deep paper research is:

search_papers → download_paper → read_paper

list_papers shows what you have locally. semantic_search searches across your local collection.

---

1. Paper Search

Search arXiv with optional category, date, and boolean filters. Enforces arXiv's 3-second rate limit automatically. If rate limited, wait 60 seconds before retrying.

result = await call_tool("search_papers", {
    "query": "\"KAN\" OR \"Kolmogorov-Arnold Networks\"",
    "max_results": 10,
    "date_from": "2024-01-01",
    "categories": ["cs.LG", "cs.AI"],
    "sort_by": "date"   # or "relevance" (default)
})

Supported categories include cs.AI, cs.LG, cs.CL, cs.CV, cs.NE, stat.ML, math.OC, quant-ph, eess.SP, and more. See tool description for the full list.

2. Paper Download

Download a paper by its arXiv ID. Tries HTML first, falls back to PDF. Stores the paper locally for read_paper and semantic_search. The response includes content_length, returned_chars, next_start, and is_truncated so clients can safely page through very large papers without mistaking client-side output caps for failed downloads.

result = await call_tool("download_paper", {
    "paper_id": "2401.12345"
})

# For very large papers, request bounded chunks:
result = await call_tool("download_paper", {
    "paper_id": "2401.12345",
    "start": 0,
    "max_chars": 50000
})

For older papers that only have a PDF, install the [pdf] extra: uv pip install -e ".[pdf]"

3. List Papers

List all papers downloaded locally. Returns arXiv IDs only — use read_paper to access content.

result = await call_tool("list_papers", {})

4. Read Paper

Read the full text of a locally downloaded paper in markdown. Requires download_paper to be called first. Use start and max_chars with the returned next_start value to page through large papers.

result = await call_tool("read_paper", {
    "paper_id": "2401.12345"
})

result = await call_tool("read_paper", {
    "paper_id": "2401.12345",
    "start": 50000,
    "max_chars": 50000
})

📝 Research Prompts

The server offers specialized prompts to help analyze academic papers:

Paper Analysis Prompt

A comprehensive workflow for analyzing academic papers that only requires a paper ID:

result = await call_prompt("deep-paper-analysis", {
    "paper_id": "2401.12345"
})

This prompt includes:

• Detailed instructions for using available tools (list_papers, download_paper, read_paper, search_papers)
• A systematic workflow for paper analysis
• Comprehensive analysis structure covering:
  • Executive summary
  • Research context
  • Methodology analysis
  • Results evaluation
  • Practical and theoretical implications
• Future research directions
• Broader impacts

Pro Prompt Pack

• summarize_paper: concise structured summary for one paper.
• compare_papers: side-by-side technical comparison across paper IDs.
• literature_review: thematic synthesis across a topic and optional paper set.

⚙️ Configuration

Configure through command-line options and environment variables:

Setting	Purpose	Default
--storage-path	Paper storage location	~/.arxiv-mcp-server/papers
MAX_RESULTS	Maximum search results	50
REQUEST_TIMEOUT	API timeout in seconds	60
TRANSPORT	Transport type: stdio, http, or streamable-http	stdio
HOST	Host to bind to in HTTP mode	127.0.0.1
PORT	Port to listen on in HTTP mode	8000
ALLOWED_HOSTS	Comma-separated extra allowed Host header values for Streamable HTTP DNS rebinding protection	empty
ALLOWED_ORIGINS	Comma-separated extra allowed Origin header values for Streamable HTTP DNS rebinding protection	empty
SEMANTIC_SCHOLAR_API_KEY	Optional Semantic Scholar API key. When set, citation_graph sends it as the x-api-key header; per Semantic Scholar's docs this grants a higher authenticated request-rate limit. When unset, requests are unauthenticated (unchanged behavior).	empty
SEMANTIC_SCHOLAR_MIN_REQUEST_INTERVAL	Minimum seconds between Semantic Scholar requests. 0 (default) disables pacing. An authenticated API key grants ~1 request/second across all endpoints, so set this to ~1.1 to pace requests proactively instead of bursting and relying on 429 retry/backoff.	0
CITATION_MAX_EDGES	Optional cap on citation/reference edges returned by citation_graph's legacy (non-paginated) path. Unset (default) returns all edges; a truncated flag is added when the cap bites.	empty

🧪 Testing

Run the test suite:

python -m pytest

🧪 Experimental Features

These features are not yet fully tested and may behave unexpectedly. Use with caution.

The following tools require additional dependencies and are under active development:

uv pip install -e ".[pro]"

Semantic Search

Semantic similarity search over your locally downloaded papers only. Returns empty results if no papers have been downloaded yet. Requires [pro] dependencies.

result = await call_tool("semantic_search", {
    "query": "test-time adaptation in multimodal transformers",
    "max_results": 5
})
# or find papers similar to a known paper:
result = await call_tool("semantic_search", {
    "paper_id": "2404.19756",
    "max_results": 5
})

Citation Graph

Fetch references and citing papers via Semantic Scholar. Works on any arXiv ID — no local download required.

result = await call_tool("citation_graph", {
    "paper_id": "2401.12345"
})

Optional parameters (all opt-in; omit them for the legacy full-output behavior):

• limit (integer, 1–1000): max edges per direction, using Semantic Scholar's paginated endpoints.
• offset (integer, ≥ 0): pagination offset. Applies only together with limit or compact; passing offset alone is ignored and falls through to the legacy path.
• compact (boolean): strips author lists + nested external_ids and minifies the JSON for lower token cost.
• counts_only (boolean): return only the paper's true citation/reference totals as total_citations/total_references (Semantic Scholar's scalar citationCount/referenceCount) with no edge lists — one endpoint, a small fixed payload. Takes precedence over limit/offset/compact.

Note on citation_count/reference_count in the graph modes: these count the edges returned, not the paper's true totals. The default/legacy nested call is capped by Semantic Scholar at 1000 per direction, and in paginated mode they reflect the current page. For authoritative totals use counts_only: true (which returns total_citations/total_references).

When paginating (limit or compact set), citation_count/reference_count report the edges returned in the current page, not the paper's totals. The response carries a pagination block with an independent cursor per direction — pagination.citations.next and pagination.references.next (each is the next offset, or null when that direction is exhausted). offset is a single value applied to both directions, so to page deeply through one direction, advance offset to its next; the other direction re-paginates from the same offset (references are usually small enough to fit one page).

result = await call_tool("citation_graph", {
    "paper_id": "2401.12345",
    "compact": True,
    "limit": 50
})

# True totals only (no edge lists, small fixed payload):
result = await call_tool("citation_graph", {
    "paper_id": "1706.03762",
    "counts_only": True
})
# -> {"counts_only": true, "total_citations": 180624, "total_references": 41, ...}

Research Alerts

Save topic watches and poll for newly published papers since the last check. Uses the same query syntax as search_papers.

# Register a watch (idempotent — calling again updates the existing watch)
await call_tool("watch_topic", {
    "topic": "\"multi-agent reinforcement learning\"",
    "categories": ["cs.AI", "cs.LG"],
    "max_results": 10
})

# Check all watches — returns only papers published since last check
result = await call_tool("check_alerts", {})

# Check a single watch
result = await call_tool("check_alerts", {"topic": "\"multi-agent reinforcement learning\""})

Advanced Prompts

summarize_paper, compare_papers, and literature_review for deeper research workflows. Requires [pro] dependencies.

---

📄 License

Released under the Apache License 2.0. See the LICENSE file for details.

---

arxiv-mcp-pro is maintained by Logan Rooks and builds on arxiv-mcp-server, originally created by Joseph Blazick and the Pearl Labs Team. Released under Apache-2.0.