Paper Pilot

Your AI's research copilot.

Your AI Googles when you say "research." Paper Pilot actually searches real academic databases, downloads the PDFs, reads them cover to cover, and gives you evidence with citations.

Quick start

uvx paper-pilot

That's it. Or install it:

pip install paper-pilot

How it works

graph LR
    A[Prompt] --> B[Search 6 databases]
    B --> C[Resolve OA PDFs]
    C --> D[Download & read]
    D --> E[Extract evidence]
    E --> F[Render figures]
    F --> G[Markdown report]
    G --> H[Zotero sync]

One prompt. Six academic databases. Real PDFs. Real citations.

Research retrieval-augmented generation, deep-read the top papers, and compare the methods.

Your AI will:

1. Search Semantic Scholar, OpenAlex, arXiv, Crossref, and Europe PMC

2. Find the open-access PDFs, not just abstracts

3. Download and read them cover to cover

4. Extract evidence chunks with source attribution

5. Render specific pages so it can see the figures and tables

6. Write a structured Markdown report

7. Save everything into your Zotero library

vs. alternatives

MCP client setup

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "paper-pilot": {
      "command": "uv",
      "args": ["--directory", "/path/to/paper-pilot", "run", "paper-pilot"],
      "env": {
        "OPENALEX_EMAIL": "you@example.com",
        "UNPAYWALL_EMAIL": "you@example.com",
        "ZOTERO_LOCAL": "true",
        "SCIHUB_ENABLED": "false"
      }
    }
  }
}

Claude Code

claude mcp add --scope user paper-pilot -- uv --directory /path/to/paper-pilot run paper-pilot

Codex

Add to ~/.codex/config.toml:

[mcp_servers.paper_pilot]
command = "uv"
args = ["--directory", "/path/to/paper-pilot", "run", "paper-pilot"]

[mcp_servers.paper_pilot.env]
OPENALEX_EMAIL = "you@example.com"
ZOTERO_LOCAL = "true"

Streamable HTTP mode

paper-pilot --transport streamable-http --host 127.0.0.1 --port 8000

Tools

Sci-Hub integration (opt-in)

Sci-Hub access is disabled by default. To opt in:

SCIHUB_ENABLED=true

Once enabled, use search_scihub and download_scihub_paper directly, or pass include_scihub=True to research_topic / deep_read_topic for automatic fallback.

Disclaimer: Sci-Hub integration is provided strictly for educational and research purposes. Users are solely responsible for compliance with applicable laws and institutional policies.

Who uses this

PhD students that don't want to spend a week on a literature review. Point it at your thesis topic, get back a structured comparison with real citations and the PDFs already in Zotero.

Research labs that want to scan preprints weekly and auto-file them. Run research_topic on a schedule and keep your group library current.

AI builders that need their agents to work with real academic papers instead of web scraping snippets.

Configuration

OPENALEX_EMAIL=you@example.com        # Required for polite API access
UNPAYWALL_EMAIL=you@example.com       # Required for OA resolution
SEMANTIC_SCHOLAR_API_KEY=             # Optional, higher rate limits

# Local Zotero
ZOTERO_LOCAL=true
ZOTERO_LIBRARY_TYPE=user

# Web Zotero API (alternative)
ZOTERO_LIBRARY_ID=
ZOTERO_API_KEY=

# Sci-Hub (disabled by default)
SCIHUB_ENABLED=false

# Storage
PAPER_PILOT_DATA_DIR=./data

# Institutional networks
HTTP_PROXY=
HTTPS_PROXY=
SSL_CERT_FILE=

Project structure

src/paper_pilot/
  server.py              MCP tools and pipeline orchestration
  config.py              Environment and settings
  services/
    academic.py          Multi-source scholarly search
    open_access.py       OA resolution and PDF downloads
    scihub.py            Sci-Hub paper resolution (opt-in)
    deep_read.py         Full-text extraction and page rendering
    zotero.py            Local and web Zotero integration
    reporting.py         Markdown report generation
    libgen.py            Supplementary LibGen support

Architecture details: docs/ARCHITECTURE.md

For AI agents

• AGENTS.md -- shared operating guide

• CLAUDE.md -- Claude Desktop and Claude Code setup

• CODEX.md -- Codex setup

• docs/CLIENTS.md -- side-by-side client comparison

Contributing

PRs welcome. The most impactful areas:

• New scholarly source adapters

• Better OA resolution logic

• PDF parsing improvements

• More MCP client configs

See CONTRIBUTING.md.

Disclaimer

This tool is designed for academic research and educational purposes only. Open-access features use only legal, publicly available sources. Sci-Hub and LibGen integrations are disabled by default and provided as opt-in features.

License

MIT. Do whatever you want with it.

If this helps your research, star the repo and tell a colleague.