shelf-mcp

A personal library MCP server for books, movies, TV shows and games. Runs as a remote MCP server so the same library is reachable from Claude on desktop and mobile, and adds items from a photo of a shelf.

Runs entirely on free tiers: Prefect Horizon for hosting and OAuth, Neon for Postgres, Open Library and Google Books for metadata.

How the photo scan works

There is no OCR or vision service in this server, on purpose. When you attach a shelf photo in the Claude app, the model reads the spines itself and calls stage_scan with structured candidates. The server resolves each against Open Library and Google Books, checks for duplicates by ISBN and title similarity, scores its confidence, and returns the batch for review. Nothing enters the library until you approve it and confirm_import runs.

That staging step is not ceremony. Spine reading fails in predictable ways — vertical text, occluded spines, publisher logos read as authors — and the resolver corrects most of it, but not all.

Layout

server.py            MCP tools. Thin wrappers, no logic.
shelf/
  config.py          Environment settings
  db.py              asyncpg pool (PgBouncer-safe)
  models.py          Shared types and input models
  enrich/            Open Library + Google Books, confidence scoring
  repo/              SQL only
  service/           Business logic — the REST API will import this
migrations/          Schema

The service layer never imports FastMCP. When the web app arrives it sits beside server.py and calls the same functions.

Setup

Requires Python 3.11+.

git clone <your-repo> && cd shelf-mcp
pip install -e .

# Neon console -> Connect -> Pooled connection string
export DATABASE_URL="postgresql://...-pooler.../neondb?sslmode=require"

psql "$DATABASE_URL" -f migrations/001_generalize_schema.sql
fastmcp inspect server.py:mcp      # shows what Horizon will see
python server.py                   # local stdio run

Deploying to Horizon

1. Push to GitHub.
2. At horizon.prefect.io, sign in with GitHub and pick the repo.
3. Entrypoint server.py:mcp. Turn Authentication on.
4. Add DATABASE_URL as a secret.
5. Deploy. Test each tool in the Inspector before connecting anything.
6. In Claude: Settings → Connectors → Add custom connector → paste https://<name>.fastmcp.app/mcp.

Connectors are account-level, so it appears on your phone with no separate mobile setup. Pushes to main redeploy automatically.

The data model, briefly

Three ideas do most of the work:

Ownership and progress are separate. Ownership belongs to the object (owned, wishlist, lent, borrowed, sold, gone); progress belongs to you (unstarted, in_progress, finished, abandoned). You can finish a book and lend it out, and both facts survive.

Progress is a history. One row per read-through, watch-through or playthrough, each with its own dates and rating. Rereading appends rather than overwriting, so your 2019 opinion is still there. A partial unique index allows only one in_progress record per item.

Copies are separate from items. One canonical set of metadata, many things you own. The paperback and the audiobook of the same book are one item with two copies.

Kinds and statuses are text with CHECK constraints rather than Postgres enums, so adding boardgame or podcast later is a constraint swap instead of an ALTER TYPE dance.

Enrichment coverage

Books resolve well. Movies, TV and games do not resolve at all — TMDB and IGDB both require credentials, and wiring them in would cost this server its "free, no signup" property. Add them in shelf/enrich/ behind an optional key when you want them; nothing else has to change.

Backups

Neon's free plan keeps a 6-hour restore window and has no scheduled backups. This is your canonical data, so dump it somewhere periodically:

pg_dump "$DATABASE_URL" --no-owner --no-acl -Fc -f "shelf-$(date +%F).dump"

Not done yet

• Movies, TV and games work as data but have no enrichment.
• No REST API yet; the service layer is shaped for one.
• Covers are stored as URLs pointing at Open Library and Google, not copied.