paper-pilot

Paper Pilot

Let Codex and Claude find, download, and read full research papers.

Search six academic databases, read methods and results page by page, inspect figures, and get back to the decision you are trying to make. Paper Pilot is a local MCP server; your existing AI agent does the reasoning.

Install · Real example · Reading guide · Report a problem

Quick start

Install uv and Git if needed. Choose your client:

Codex

codex mcp add paper_pilot -- uvx --from git+https://github.com/aytzey/paper-pilot paper-pilot

Claude Code

claude mcp add --scope user paper-pilot -- uvx --from git+https://github.com/aytzey/paper-pilot paper-pilot

Restart your client, then ask:

Use Paper Pilot to find “Attention Is All You Need”. Read the full paper, inspect the architecture figure, and explain the method and its limitations with PDF page citations.

No account, API key, email setup, or Zotero installation is required by Paper Pilot. Your AI client’s own access and usage costs still apply. The first launch installs Python dependencies; academic APIs can rate-limit requests.

Claude Desktop or Cursor: use the copyable JSON configuration.

Try the tools without an AI client:

uvx --from git+https://github.com/aytzey/paper-pilot paper-pilot demo "retrieval augmented generation"

The CLI downloads accessible papers, saves a reading pack, and opens a citation graph. It does not run an LLM or write a finished research conclusion. Results go into ./data/ by default. These commands install from GitHub; a PyPI release is not required.

See what reaches your agent

In a recorded stdio MCP check, Attention Is All You Need was delivered as 15 pages of text across four responses. All 39,498 extracted characters arrived in order. The original 2,215,244-byte PDF also arrived unchanged through both supported PDF transfer paths.

Read the walkthrough and reproduction steps or inspect the verification data. This verifies delivery, not model comprehension. Codex and Claude UI sessions were not tested in that check.

Research a practical decision

Start with something you need to decide:

I want to build an inexpensive circuit to measure soil pH. Use Paper Pilot to investigate soil science, electrode materials, and electronics, starting with recent papers and following foundational references. Read the decisive papers in full. Compare cost, calibration, drift, and measurement conditions. Recommend an approach, cite the evidence, and propose the first experiment to validate it.

The server supplies research instructions alongside its tools: split the question across disciplines, continue the relevant searches, inspect the full papers, seek contrary evidence, and disclose gaps before recommending an approach.

Other useful starting points:

Search covers Semantic Scholar, OpenAlex, arXiv, Crossref, Europe PMC, and DOAJ. A working PDF is used directly; missing or failed PDFs are resolved through Unpaywall, with OpenAlex recovery if its API fails. Zotero sync is optional.

How full-paper reading works

• Text: read_pdf_text returns consecutive pages with continuation cursors, including pages longer than a single response.
• Figures and tables: render_pdf_pages returns page images for visual inspection.
• Original file: read_pdf_document provides the PDF when your agent needs it and the client supports that delivery path.
• Evidence trail: retain source, DOI, PDF page, access location, and extraction warnings.

The agent must follow every continuation to complete a text read. Scanned PDFs without a text layer are reported as unreadable; OCR is outside the project scope. Search results reflect returned provider pages, so exhaustive literature coverage is not guaranteed.

See the tool-level reading guide for exact calls, access rules, and limits.

MCP client setup

For Claude Desktop or Cursor, add this server to your MCP configuration:

{
  "mcpServers": {
    "paper-pilot": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/aytzey/paper-pilot", "paper-pilot"]
    }
  }
}

Ready-to-copy files: Claude Desktop · Cursor · Codex.

On Windows, if the client cannot find uvx, use the executable’s full path from where.exe uvx. Keep the arguments unchanged. Client setup covers configuration locations, local checkouts, updates, PDF capabilities, and optional Zotero setup.

Where Paper Pilot fits

Use it when you want your existing agent to research a question across disciplines and inspect the actual papers. If your main task is different, these projects are also worth a look:

These are different starting points, not a quality ranking. Paper Pilot does not include its own LLM or require a vector database.

Contribute a real research case

Try a paper or decision you know well. If the agent misses a source, cannot retrieve a PDF, or loses part of a page, open an issue with the DOI, client, and failed step. A small reproducible case is particularly useful.

For code contributions, see CONTRIBUTING.md. The most useful work is reliable source access, reading correctness, and verified client instructions.

Architecture · Agent instructions · Codex guide · Claude guide · Optional integrations

MIT licensed. If this is useful for your next research task, star Paper Pilot to keep it handy. Sharing a case that worked helps other people decide whether to try it.