Paperboy

What michaelellis003/paperboy MCP server does

michaelellis003/paperboy MCP server connects Claude to a paper-discovery, Zotero cataloguing, and e-reader delivery workflow. It can search OpenAlex or arXiv, recommend related papers, add works to a Zotero library, and deliver available PDFs by email or Dropbox. Books can also be catalogued as Zotero book items, but the book workflow does not deliver them to an e-reader.

The system separates library management from delivery. A paper may be recorded in Zotero without being queued or sent, while a PDF already on disk can be attached to a library item and optionally delivered in the same operation. Papers without an open-access PDF remain valid library records rather than being treated as failed requests.

How it works

michaelellis003/paperboy MCP server uses Zotero as its persistent source of truth when Zotero is configured. Queued papers are placed in a Reading Queue collection, which is created when needed. After successful delivery, the item receives a sent-to-ereader tag, allowing later conversations to skip it. Topical collections can be suggested from the paper and existing collection names; filing does not remove queue membership.

Paper identification accepts arXiv IDs, DOIs, URLs, and titles. Approximate title matches can produce a confirmation candidate instead of silently selecting an uncertain result. Recommendations combine Semantic Scholar citation-graph results seeded from the Zotero library with keyword discovery based on conversation interests, while excluding papers already held in the library.

Email delivery supports Kindle, PocketBook, and other devices with an email intake address. Dropbox delivery is intended for Kobo devices using native Dropbox synchronization. Email batches observe Kindle’s stated limits of 25 attachments and 50 MB per message.

Setup and configuration

For a local installation, the documented setup flow is uv sync && uv run paperboy setup. The interactive wizard asks for device-specific credentials and validates them as they are entered. Kindle and PocketBook require a send-to-device address plus an SMTP app password. Kobo requires a Dropbox application, OAuth approval, and a contact email. Optional Zotero queue features require a Zotero API key; the library ID is detected automatically.

Configuration can also be entered through a .env file. The server loads that file from its working directory, or can use PAPERBOY_ENV to point to another location. Dropbox delivery requires a Full Dropbox-scoped application when using the Kobo folder, with DROPBOX_FOLDER set to /Apps/Rakuten Kobo.

A Cloud Run deployment is available through the repository’s deployment script. Remote clients connect to the /mcp endpoint with a bearer token, while claude.ai and the Claude mobile app can use Google sign-in in the described deployment configuration.

Tools and capabilities

michaelellis003/paperboy MCP server exposes tools for searching and recommending papers, sending individual papers, managing the reading queue, and sending all unsent queue items. It also supports adding papers to Zotero without delivery, cataloguing books by ISBN, book DOI, or title, and attaching existing PDFs with supplied metadata.

Additional tools list collections, file or unfile papers, remove queue entries, display per-item queue status, and report missing configuration without exposing secrets. Delivery receipts include file sizes and identify items that could not be sent.

Limitations and notes

Zotero is not mandatory for one-off searches and sends, but queue persistence, collection filing, and cross-session duplicate protection depend on it. Delivery requires an accessible PDF; a paywalled or unavailable paper can still be catalogued. Dropbox’s Kobo workflow depends on the device syncing the specified Kobo application folder. Remote bearer tokens grant owner-level access to delivery and Zotero operations, so they should be treated like passwords.