ArXiv MCP Server

🔍 Enable AI assistants to search and access arXiv papers through a simple MCP interface.

The ArXiv MCP Server provides a bridge between AI assistants and arXiv's research repository through the Model Context Protocol (MCP). It allows AI models to search for papers and access their content in a programmatic way.

🤝 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-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

Installing via Smithery

To install ArXiv Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install arxiv-mcp-server --client claude

Installing via Claude Desktop (.mcpb)

The .mcpb bundle is the one-click install path for Claude Desktop on macOS. It bundles the server code and Python package dependencies, so users do not need uv, pip, or manual MCP JSON configuration. Python 3.11+ must still be available on the user's machine.

1. Download the artifact matching your Mac from the latest release:
   • Apple Silicon: arxiv-mcp-server-darwin-arm64-<version>.mcpb
   • Intel: arxiv-mcp-server-darwin-x86_64-<version>.mcpb
2. In Claude Desktop open Settings → Extensions (or drag-and-drop the file onto the Claude Desktop window).
3. Click Install and, when prompted, set your preferred paper storage directory (defaults to ~/.arxiv-mcp-server/papers).

Claude Desktop launches the bundled server over stdio — no configuration file edits needed.

Installing Manually

Important — use uv tool install, not npm/pnpm or uv pip install

This project publishes the supported server as a Python package on PyPI. Do not install arxiv-mcp-server with npm install, pnpm add, or npx arxiv-mcp-server: the npm package with this name is an unrelated third-party package and has its own Python-detection wrapper.

Running uv pip install arxiv-mcp-server installs the package into the current virtual environment but does not place the arxiv-mcp-server executable on your PATH. You must use uv tool install so that uv creates an isolated environment and exposes the executable globally:

uv tool install arxiv-mcp-server

After this, the arxiv-mcp-server command will be available on your PATH.

PDF fallback (older papers): Most arXiv papers have an HTML version which the base install handles automatically. For older papers that only have a PDF, the server needs the [pdf] extra (pymupdf4llm). Install it with:

uv tool install 'arxiv-mcp-server[pdf]'

You can verify it with:

arxiv-mcp-server --help

If you previously ran uv pip install arxiv-mcp-server and the command is missing, uninstall it and re-install with uv tool install as shown above.

For development:

# Clone and set up development environment
git clone https://github.com/blazickjp/arxiv-mcp-server.git
cd arxiv-mcp-server

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

# Install with test dependencies (development only — no global executable)
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": "uvx",
      "args": ["arxiv-mcp-server"]
    }
  }
}

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

Add this configuration to your MCP client config file:

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

For Development:

{
    "mcpServers": {
        "arxiv-mcp-server": {
            "command": "uv",
            "args": [
                "--directory",
                "path/to/cloned/arxiv-mcp-server",
                "run",
                "arxiv-mcp-server",
                "--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-server --storage-path /path/to/papers

Then configure an MCP client that supports Streamable HTTP:

{
    "mcpServers": {
        "arxiv-mcp-server": {
            "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 tool install 'arxiv-mcp-server[pdf]'

3. List Papers

List all papers downloaded locally. Returns arXiv IDs only —