Paper Download MCP Server

MCP server for downloading academic papers from multiple sources with intelligent routing.

Note: This project is built on top of scihub-cli, adapting its core functionality for MCP integration. If you find this useful, consider starring both projects!

Features

• Multi-Source Support: Downloads from multiple sources with automatic fallback

  • arXiv: Prioritized for preprints (free, no API key needed)

  • Unpaywall: For open access papers (requires email)

  • Direct PDF: Handles direct PDF URLs

  • PMC: PubMed Central articles

  • HTML Landing: Extracts PDF links from article pages

  • Sci-Hub: Fallback for older papers (coverage-driven)

  • CORE: Additional OA fallback

• Intelligent Routing: Priority-based source selection with year-aware routing

• 3 MCP Tools:

  • paper_download - Download single paper by DOI or URL

  • paper_batch_download - Download multiple papers with progress reporting

  • paper_metadata - Get paper metadata without downloading PDF

• Clean Filenames: [YYYY] - Paper Title.pdf format

• Rate Limiting: Built-in delays for API compliance

• Comprehensive Error Messages: Actionable suggestions on failures

Installation

For Users (Recommended)

No manual installation required! Use uvx for automatic environment management:

For Developers

Configuration

Required Environment Variables

• PAPER_DOWNLOAD_EMAIL: Your email address (required for Unpaywall API compliance)

  • Example: researcher@university.edu

  • Used for Unpaywall API tracking and contact purposes

Optional Environment Variables

• PAPER_DOWNLOAD_OUTPUT_DIR: Default output directory (default: ./downloads)

Claude Desktop Setup

Add to your claude_desktop_config.json:

After configuration, restart Claude Desktop.

Tools

paper_download

Download a single academic paper by DOI or URL.

Parameters:

• identifier (required): DOI or URL (e.g., 10.1038/nature12373)

• output_dir (optional): Output directory (default: ./downloads)

Example:

Returns:

• Markdown with download details (file path, size, source, timing)

• Error message with suggestions if download fails

paper_batch_download

Download multiple papers sequentially with progress reporting.

Parameters:

• identifiers (required): List of DOIs or URLs (1-50 maximum)

• output_dir (optional): Output directory (default: ./downloads)

Example:

Returns:

• Markdown summary with statistics

• List of successful downloads

• List of failed downloads with errors

Note: Downloads are sequential with 2-second delays for rate limiting.

paper_metadata

Retrieve paper metadata without downloading the PDF.

Parameters:

• identifier (required): DOI or URL

Example:

Returns:

• JSON with paper details:

  • DOI, title, year, authors, journal

  • Open access status

  • Available download sources

How It Works

Intelligent Source Routing

The server uses priority routing to keep fast sources first:

1. arXiv IDs/URLs: Try arXiv first, then OA sources if needed

2. DOIs (year < 2021): OA sources first, Sci-Hub last

3. DOIs (year ≥ 2021): OA sources only (Sci-Hub has no coverage)

4. Year unknown: OA sources first, Sci-Hub last

Download Process

1. Normalize DOI from URL/identifier

2. Detect publication year via Crossref API (DOIs only)

3. Route to appropriate source based on priority/year

4. Download PDF with retry on failure

5. Validate file (PDF header, size check)

6. Generate filename: [YYYY] - Title.pdf

7. Return absolute file path

Rate Limiting

• 2-second delay between batch downloads

• Respects Unpaywall API limits (~100k requests/day)

• Built-in exponential backoff retry (3 attempts max)

Troubleshooting

"PAPER_DOWNLOAD_EMAIL environment variable is required"

Solution: Set the email in your Claude Desktop config (see Configuration section above).

"Paper not found in any source"

Possible causes:

• Invalid or incorrect DOI

• Paper too recent (not yet indexed)

• Paper behind paywall with no open access version

• Sci-Hub mirrors temporarily unavailable

Solutions:

• Verify DOI on doi.org

• Use paper_metadata to check availability

• Try again later (mirrors may recover)

Download times out

Causes:

• Slow network connection

• Sci-Hub mirror selection taking too long

• Large PDF file

Solutions:

• Check internet connection

• Retry (mirror selection is cached after first success)

• Single papers typically complete in <15 seconds

Downloaded file is corrupted

The server validates PDFs before returning. If you encounter corruption:

1. Check disk space

2. Verify file permissions in output directory

3. Try different paper (may be source issue)

Testing

MCP Inspector

Test the server with MCP Inspector:

Unit Tests

Legal Notice

IMPORTANT: This tool provides access to academic papers through multiple sources:

• Unpaywall (https://unpaywall.org): Legal open-access aggregator operated by OurResearch. Recommended and prioritized when available.

• Sci-Hub: Operates in a legal gray area. While it provides access to research, it may violate copyright laws in some jurisdictions. Use at your own risk.

User Responsibilities:

• You are responsible for compliance with applicable copyright laws in your jurisdiction

• This tool is intended for research and educational purposes only

• The maintainers assume no liability for how you use this tool

• When possible, prefer legal open-access sources (Unpaywall)

By using this tool, you acknowledge these legal considerations and agree to use it responsibly.

Project Structure

Architecture

Layer Architecture

1. FastMCP Server Layer: Protocol handling, tool registration, config validation

2. MCP Tools Layer: Request parsing, response formatting, async coordination

3. Models & Formatters: Data validation, output serialization

4. scihub_core Layer: Academic paper logic (unchanged from scihub-cli)

Async Pattern

All tools use asyncio.to_thread() to wrap synchronous scihub-cli code:

This preserves the battle-tested scihub-cli code without modifications.

Performance

Note: First download may take longer (5-10s) due to mirror selection. Subsequent downloads use cached mirror.

Contributing

For Maintainers: Syncing from scihub-cli

The scihub_core/ directory contains code copied from the upstream scihub-cli project. When bugs are fixed or features added to scihub-cli:

Workflow:

1. Fix/implement in scihub-cli project first

2. Run tests and commit to scihub-cli

3. Copy updated files to paper-download-mcp/src/paper_download_mcp/scihub_core/

4. Test MCP server functionality

5. Commit with message referencing upstream commit:

   sync: Update <file> from scihub-cli (<description>) Synced from scihub-cli commit <hash> <details of changes>

Last sync: scihub-cli@9787efc (2024-12-02) - Fixed year type bug in UnpaywallSource

License

MIT License - See LICENSE file for details

Credits

• Built with FastMCP

• Uses scihub-cli as core download engine

• Metadata from Unpaywall and Crossref

Support

For issues or questions:

1. Check the Troubleshooting section above

2. Open an issue on GitHub (include error messages and steps to reproduce)

Disclaimer: This tool is provided as-is for research and educational purposes. Users assume all responsibility for compliance with applicable laws and regulations.