Use Papyrium with AI agents

Connect your local library to Claude Code, Claude Desktop, Codex, or another MCP-compatible agent.

What it does

Papyrium can run a local MCP (Model Context Protocol) server, giving compatible AI agents structured access to your books, metadata, categories, tags, collections, reading lists, highlights, notes, bookmarks, and other library context.

That lets your agent help organize the library you already have. The server runs on your machine, and your AI client controls what it sends to its model.

What you can do

Once connected, you can talk to your library through your agent. For example:

"Find uncategorized books and suggest categories."
"Clean up books with missing authors, publishers, or ISBNs."
"Find duplicate books in my Inbox and merge each into a single entry."
"Find near-duplicate tags and merge them."
"Build a reading list about distributed systems from books I already own."
"What did I highlight about CRDTs across all my books?"

Search and read your library

Read tools are available as soon as the MCP server is enabled — no extra opt-in needed. Your agent can:

Search and discover

Search books with structured filters — by author, tag, category, series, language, year, reading status, progress, metadata gaps, collection, or location. Get a whole-library summary with statistics and cleanup targets.

Read annotations

Retrieve highlights, notes, and bookmarks for any book. Search across annotations in your entire library by keyword — useful for finding what you marked across many books.

Browse structure

Browse categories, tags, series, authors, physical folders, collections, and reading lists. Fetch full book details including metadata, reading progress, and collection membership.

Organize your library

Write tools are off by default. In Settings → MCP there are two independent opt-ins — enable only what you need.

Allow edits

Clean up metadata

Categorize and tag books in batches, set authors, assign series, and fill in fields like title, publisher, ISBN, language, edition, year, pages, and description.

Clean up vocabulary

Create, rename, and delete unused categories, tags, series, and authors. Merge near-duplicate entries by moving books onto the right entry and deleting the empty duplicate.

Curate collections and reading lists

Create collections and reading lists, add or remove books from them, and rename existing lists.

Allow deletions

Resolve duplicates

Merge duplicate copies of a book into a single entry — every file and all your highlights are kept — or send a redundant copy to your system Trash. Both preview the change first, and the agent can see exactly which fields differ between copies before choosing.

Move files

Relocate book files between connected locations. Previews what would move before making any changes.

Review and undo what your agent did

Every write the agent makes is recorded in the Tools → MCP Activity tab. Each entry shows the operation, the affected book (with a cover thumbnail and a one-click Select in library shortcut), and a field-level diff for every metadata change — old value and new value, side by side. Bulk actions like tagging or categorizing expand to show every affected book.

Most operations have a one-click Undo: scalar metadata edits, tag / category / author / series assignments, renames, and newly created taxonomy entries that aren't yet in use.

File-changing operations — moving, trashing, or merging duplicates — can't be undone from the log. Those tools preview with dryRun first, and trashed files go to your system Trash where they can be recovered manually.

Safety model

The MCP server is off by default
Write access has two independent opt-ins — Allow edits and Allow deletions — enable only what you need
Every applied write is logged to Tools → MCP Activity — metadata edits with a before-and-after diff, bulk actions with the list of affected books
One-click Undo for metadata edits, tag / category / author / series changes, and renames
Bulk and file-changing tools support dryRun — preview what would change before committing
Repeating an action is safe — re-adding a tag or re-applying the same edit does nothing extra
Assignment tools work by ID only and never auto-create entries — no accidental near-duplicates
Taxonomy entries can only be deleted when no books reference them

Setup

Enable the server. Open Settings → MCP and toggle it on. The server starts on http://127.0.0.1:7654/mcp.
Connect your client. For Claude Code, Codex, or another MCP-compatible client, add the server URL — the Settings panel shows the exact endpoint and a copy-ready config snippet.
Using Claude Desktop? Claude Desktop currently can't connect to a local http URL directly, so click Add to Claude Desktop in the same Settings panel — Papyrium configures a small local bridge for it automatically. Restart Claude Desktop afterward to connect.
Optionally enable writes. To let the agent edit metadata, categorize books, or manage collections, enable Allow edits. To also allow moving, merging, or trashing files, enable Allow deletions. Both are off by default.

The server runs only while Papyrium is open. When you close the app, the server stops.

Privacy and limits

The MCP server binds to 127.0.0.1 (localhost only) — it is not reachable from the network.

Through MCP, Papyrium serves book metadata and user-created content such as highlights, notes, and bookmarks, plus the file locations (paths) of your books, to the AI client running on your machine. Your AI client may send some of that context to its own AI provider, depending on how that client works.

Book files and extracted book text are not served through the current MCP server. Search is structured and keyword-based today; semantic search and full-text book-content search are not part of the current MCP server.

For how books and folders get into your library, see Folders & Imports. For how collections and reading lists work, see Collections. For how duplicate detection works, see Duplicates.

Need help?

If something isn't working, email hello@papyriumlib.com or open a bug report on GitHub.