book-recs

# Book Recommendations MCP Server A personal MCP server that helps you decide what to read next from your own TBR list. Give it a vibe ("something dark and twisty" or "a cozy slow read") and it pulls your StoryGraph TBR, checks Goodreads ratings, and tells you whether each candidate is on Kindle Unlimited. ## How it works **Data sources:** | Source | What it provides | Auth | |---|---|---| | StoryGraph | Your TBR list, mood tags, pace, genre | Your credentials (stored in `.env`) | | Goodreads | Community ratings | None — public pages | | Amazon | Kindle Unlimited availability | None — public pages | **Typical Claude interaction:** > "I'm in the mood for something tense and atmospheric, not too long" Claude calls `get_tbr` to fetch your full TBR with StoryGraph mood tags, shortlists candidates that match the vibe, calls `get_rating` and `get_kindle_unlimited` for each, then returns ranked picks with ratings and KU status. ## Setup **1. Install dependencies** ```bash python -m venv .venv source .venv/bin/activate pip install -e . playwright install chromium ``` **2. Configure credentials** ```bash cp .env.example .env ``` Edit `.env` with your StoryGraph details: ``` STORYGRAPH_EMAIL=your@email.com STORYGRAPH_PASSWORD=yourpassword STORYGRAPH_USERNAME=your-storygraph-username ``` Your StoryGraph username is the handle in your profile URL: `app.thestorygraph.com/profile/USERNAME` **3. Run the server** ```bash python server.py ``` The server starts on `http://0.0.0.0:8000` by default. Set `PORT` in `.env` to change it. ## MCP tools | Tool | Description | |---|---| | `get_tbr()` | Fetch full TBR from StoryGraph (cached 1 hour) | | `get_rating(title, author)` | Goodreads avg rating + count (cached 24 hours) | | `get_kindle_unlimited(title, author)` | KU availability + Amazon URL (cached 24 hours) | | `refresh_tbr()` | Force re-scrape TBR, bypassing cache | ## Connecting to Claude Add this to your Claude MCP config (e.g. `~/.claude/claude_desktop_config.json` for the desktop app, or your Claude Code settings): ```json { "mcpServers": { "book-recs": { "url": "http://localhost:8000/mcp" } } } ``` When hosting remotely, replace `localhost:8000` with your server's address. ## Notes on scraping StoryGraph requires a login, handled automatically via Playwright. After the first login, a session is saved to `.storygraph_session.json` so subsequent calls don't need to re-authenticate — this file is excluded from git. The StoryGraph CSS selectors in `scrapers/storygraph.py` may need tuning if the site updates its HTML. If `get_tbr` returns empty results, inspect your TBR page in browser DevTools and update the selectors around line 55. ## Hosting The server uses [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports), the standard for remote MCP servers. It will deploy as-is to any platform that runs a Python process — Railway, Render, Fly.io, etc. The only requirement is that your `PORT` env var matches what the platform assigns.