📄 paper-mcp

An MCP server built with FastMCP for paper, citation, author, and bibliography search. Run it in one command with uvx — no manual install needed.

✨ Features

Paper tools

Author and source tools

paper_search accepts sources, year range, venue, author, publication type, minimum citations, open-access-only, and relevance/year/citation sorting. Full text uses arXiv HTML → structured open-access PDF extraction → Lightpanda → abstract. Responses from repeated Semantic Scholar searches and batch lookups are cached in memory.

🚀 Quick Start

Run without installing (uvx)

# stdio mode — for Claude Desktop / most MCP clients
uvx paper-mcp

# SSE mode — for remote or multi-client setups
uvx paper-mcp --transport sse --port 8000

uvx downloads, installs (in an isolated env), and runs the package — zero setup.

Install permanently

uv tool install paper-mcp
paper-mcp                        # now available globally
paper-mcp --transport sse

Local development

git clone https://github.com/imnotdev25/paper-search
cd paper-search
uv sync                                 # install all deps from pyproject.toml
uv run paper-mcp                 # run directly
uv run paper-mcp --transport sse

🖥 Claude Desktop Config

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "papers": {
      "command": "uvx",
      "args": ["paper-mcp"]
    }
  }
}

No Python paths, no venv activation — uvx handles everything.

🌐 Browser Fallback (gomcp / Lightpanda)

For JS-rendered publisher pages, the server automatically starts a Lightpanda headless browser via gomcp.

One-time setup:

# Download gomcp binary from GitHub releases:
# https://github.com/lightpanda-io/gomcp/releases

# Then download the Lightpanda browser binary:
gomcp download

If gomcp is not installed, the server still works — browser-dependent paths fall back to abstract/metadata gracefully.

🏗 Architecture

Claude (LLM)
    │  MCP (stdio or SSE)
    ▼
paper-mcp  [FastMCP, Python]
    │
    ├── Semantic Scholar API  ──  metadata, citations, references
    ├── arXiv API + HTML      ──  preprint info + full text
    ├── Crossref + Unpaywall  ──  DOI metadata, BibTeX, OA PDFs
    ├── OpenAlex / PubMed / DBLP ── corpus-specific search
    └── gomcp SSE  ───────────── Lightpanda browser (JS fallback)
             │  CDP
             └── Lightpanda Browser (headless)

📦 Publishing to PyPI

# Build
uv build

# Publish (needs PyPI token)
uv publish --token $PYPI_TOKEN

Once on PyPI, anyone can run it with uvx paper-mcp.

⚙️ CLI Options

usage: paper-mcp [-h] [--transport {stdio,sse}] [--port PORT] [--host HOST]

options:
  --transport  stdio (default) or sse
  --port       SSE port (default: 8000)
  --host       SSE host (default: 127.0.0.1)

🔑 Notes

• Set S2_API_KEY for authenticated Semantic Scholar requests.
• Set UNPAYWALL_EMAIL to a real contact address to enable Unpaywall. Requests are skipped when it is unset; no placeholder identity is sent.
• Optionally set OPENALEX_EMAIL for the OpenAlex polite pool.
• PAPER_CACHE_TTL controls the in-memory cache in seconds (default 3600; 0 disables it).
• PDF extraction is limited to open PDFs up to 25 MB and 50,000 extracted characters. Paywalled PDFs still require institutional access.

📁 Project Structure

paper-mcp/
├── pyproject.toml                  ← packaging, entry point, deps
├── README.md
├── src/
    └── paper_mcp/
        ├── __init__.py
        └── server.py               ← FastMCP tools + main()
└── tests/
    └── test_server.py              ← focused HTTP, PDF, cache, and config tests