arxiv-mcp-server

To set up the arXiv MCP server, ensure you have uv and uvx installed on your system. If you are using Kiro, allow it to register the bundled mcp.json configuration.

By default, the server manages its data (downloaded papers, source archives, alerts, and indexes) in the following directory: ~/.arxiv-mcp-server/papers

You can install the server as a persistent command on your PATH using uv tool install. Choose the variant that matches your required features:

• Base server: Standard functionality.
• Base + PDF: Adds pymupdf4llm and pymupdf-layout for papers without usable arXiv HTML.
• Base + Pro: Adds local embedding dependencies for semantic_search and reindex (operates on downloaded papers).

# 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]'

# Reinstalling a different variant
uv tool install --force 'arxiv-mcp-server[pdf]'

Follow these steps for an efficient research workflow using the server:

1. Search: Use focused queries, relevant categories, and a small result limit.
2. Abstracts: Read abstracts before committing to full paper downloads.
3. LaTeX Source: When accessing original source, list the LaTeX section outline first and retrieve only the specific sections required.
4. Full Text: For rendered text, download the paper once and use bounded, paginated reads.
5. Citations: Use the citation graph to follow references and citing papers.
6. Monitoring: Use topic watches for recurring monitoring. Note that local semantic search is only available after papers have been downloaded and indexed.

You can run the arXiv MCP server using uvx.

• Standard installation: Use the default package.
• PDF-only fallback: If you require specific PDF handling capabilities, install the package with the pdf extra.

By default, downloaded papers are stored in ~/.arxiv-mcp-server/papers.

If stdio is not practical, you can run the server as an HTTP service. The server binds to 127.0.0.1 by default and includes MCP DNS-rebinding protection.

Security Note: If using a reverse proxy, keep the process on a private interface and use ALLOWED_HOSTS and ALLOWED_ORIGINS to configure the host and origin values forwarded by the proxy.

# Start the server
TRANSPORT=http HOST=127.0.0.1 PORT=8080 \
uvx arxiv-mcp-server --storage-path /absolute/path/to/papers

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

To use a local development checkout of the server in an MCP client (like Claude Desktop), add the following configuration to your mcpServers settings, replacing /absolute/path/to/arxiv-mcp-server with the actual path to your local clone.

{
  "mcpServers": {
    "arxiv-dev": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/arxiv-mcp-server",
        "run",
        "arxiv-mcp-server"
      ]
    }
  }
}

You can install the arxiv-mcp-server in Claude Code using two methods:

1. Direct MCP Installation: Adds the server for all projects via stdio.
2. Plugin Installation: Installs the MCP connection plus the bundled arXiv research skill (recommended for richer integration).

Note: These commands require uv to be installed.

# Direct MCP installation
claude mcp add --transport stdio --scope user arxiv \
  -- uvx arxiv-mcp-server

# Plugin installation (includes research skills)
claude plugin marketplace add blazickjp/arxiv-mcp-server
claude plugin install arxiv-mcp-server@arxiv-mcp

To develop on the project, clone the repository and use uv to sync dependencies and run tests.

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 .

Install the arxiv-mcp-server in OpenAI Codex using two methods:

1. Direct MCP Installation: Adds the server via stdio.
2. Plugin Installation: Installs the MCP connection and the bundled research skill.

Configuration is shared across the Codex CLI, Codex IDE extension, and Codex in the ChatGPT desktop app.

# Direct MCP installation
codex mcp add arxiv -- uvx arxiv-mcp-server

# Plugin installation
codex plugin marketplace add blazickjp/arxiv-mcp-server
codex plugin add arxiv-mcp-server@arxiv-mcp

To prevent overwhelming the conversation context, follow this bounded and section-aware retrieval workflow:

1. Search: Use a focused query with a small max_results value.
2. Assess: Use get_abstract to check relevance before downloading full papers.
3. LaTeX Retrieval (Author-submitted source):
   • Call list_paper_latex_sections to see available sections.
   • Call get_paper_latex_section to retrieve only the specific section needed.
4. Full Text Retrieval (Rendered text):
   • Call download_paper once.
   • Use read_paper to page through content using start and max_chars parameters.
5. Reference Tracking: Use citation_graph to follow references and citing papers.
6. Monitoring: Use topic watches for ongoing monitoring. (Note: Use semantic search only after papers are downloaded and indexed locally).

To use the server with any MCP client that accepts standard MCP JSON, use the following stdio configuration.

Default Storage: Papers are stored in ~/.arxiv-mcp-server/papers. To change this, append --storage-path followed by an absolute path to the args array.

PDF Support: For older papers that require PDF conversion, use the [pdf] extra by adding --from arxiv-mcp-server[pdf] to the arguments.

{
  "mcpServers": {
    "arxiv": {
      "type": "stdio",
      "command": "uvx",
      "args": ["arxiv-mcp-server"]
    }
  }
}