Goodreads MCP
A Goodreads MCP server that discovers books/authors, enriches metadata, and performs authenticated shelf/rating write-back, with local sync, SQL, and archive tooling.
Look up books and authors by ID (
book_get,author_get) and search public book pages (goodreads-search_books)Read a user's public shelf/reviews (
review_get-shelf), optionally filtered to one shelfResolve a title or book ID into Notion-ready metadata (
enrich), with field selection, compact mode, or search-match-only (no-details)Write to your shelves: set to-read/currently-reading/read with tags and optional rating, rate, unrate, or unshelve (
shelf_set,shelf_rate,shelf_unrate,shelf_unshelve) — requires a Goodreads cookie/JWT or macOS browser auth; started/finished dates are rejected as unsupportedVerify write authentication (
shelf_auth_check)Sync/archive all syncable resources into local SQLite, incremental or full, resumable (
sync,workflow_archive), and inspect sync state (workflow_status)Run read-only ad-hoc SQL (SELECT/WITH) over synced data (
sql)Bulk-load records from a JSONL file via POST (
import)Get domain context, auth requirements, and query tips up front (
context)Agent-friendly options throughout:
--agent,--json/--csv/--plain/--quiet,--select,--compact,--dry-run,--deliver,--rate-limit, and config profiles
Provides tools for Goodreads book search, metadata extraction, author and review lookup, book enrichment, and authenticated shelf/rating write-back using a Goodreads browser session, cookie, or JWT.
Goodreads CLI (goodreads)
A command-line tool and Model Context Protocol (MCP) server for Goodreads book discovery, metadata extraction, and authenticated shelf/rating write-back, built by Sameer Bajaj.
Canonical homepage & documentation: https://sameerbajaj.com/tools/goodreads-cli/
It uses public Goodreads pages for read-only metadata and the logged-in Goodreads web GraphQL endpoint for shelf changes. Goodreads no longer issues new public API keys, so authenticated writes use your own browser session, GOODREADS_COOKIE, or GOODREADS_JWT.
Install
go install github.com/sameerbajaj/goodreads-cli/cmd/goodreads@latestVerify:
goodreads doctor
goodreads --helpRelated MCP server: anna-book-search
Quick Start
goodreads search dune
goodreads book 44767458-dune --json
goodreads enrich "Dune" --json --select metadata.title,metadata.rating,metadata.ratings_countShelf Write-Back
On macOS, goodreads can use your local Brave or Chrome Goodreads cookies automatically. It reads only Goodreads cookies, decrypts them locally through Keychain, and does not print or store them.
goodreads shelf auth-check --json
goodreads shelf set --book-id 44767458-dune --shelf currently-reading --yes --json
goodreads shelf set "Dune" --shelf read --rating 5 --tags sci-fi,classics --yes --json
goodreads shelf rate --book-id 44767458-dune --rating 5 --yes --json
goodreads shelf unrate --book-id 44767458-dune --yes --json
goodreads shelf unshelve --book-id 44767458-dune --yes --jsonSupported shelves are to-read, currently-reading, and read; aliases include want-to-read, reading, completed, and done.
Started/finished date writes are intentionally rejected for now because the current Goodreads web client did not expose a verified date mutation.
Auth Options
Automatic macOS browser auth tries Brave first, then Chrome. You can force a browser or disable auto browser auth:
GOODREADS_BROWSER=brave goodreads shelf auth-check --json
GOODREADS_BROWSER=chrome goodreads shelf auth-check --json
GOODREADS_NO_BROWSER_AUTH=1 goodreads shelf auth-check --jsonManual auth also works:
export GOODREADS_COOKIE='_session_id2=...; other_cookie=...'
goodreads shelf auth-check --json
export GOODREADS_JWT='...'
goodreads shelf auth-check --jsonYou can store config at ~/.config/goodreads-cli/config.toml:
goodreads_browser = "brave"
# or:
goodreads_cookie = "_session_id2=...; other_cookie=..."
# or:
goodreads_jwt = "..."Agent Usage
The CLI is designed for LLM and automation use:
--agentsets JSON, compact output, non-interactive mode, no color, and--yes.--dry-runpreviews writes without sending them.Mutating commands are grouped under
shelf.Write commands require
--yesunless--dry-runis used.Secrets are redacted from dry-run output.
Example for another LLM or local agent:
goodreads shelf set "The Left Hand of Darkness" --shelf currently-reading --agent
goodreads enrich "The Left Hand of Darkness" --agent --select metadata.title,metadata.rating,metadata.ratings_count,book_idMCP
Build the MCP server:
go build -o bin/goodreads-mcp ./cmd/goodreads-mcpManual Claude Desktop config:
{
"mcpServers": {
"goodreads": {
"command": "goodreads-mcp"
}
}
}Commands
goodreads search "left hand of darkness"
goodreads book 44767458-dune --json
goodreads author 58.Frank_Herbert --json
goodreads review <user_id> --json
goodreads enrich "Dune" --json
goodreads shelf auth-check --jsonRun goodreads <command> --help for command-specific flags.
Build From Source
git clone https://github.com/sameerbajaj/goodreads-cli.git
cd goodreads-cli
go test ./...
go build -o bin/goodreads ./cmd/goodreadsNotes
This project was initially scaffolded with a CLI generator, then customized for Goodreads' current public web and logged-in web behavior.
👤 Author
Developed by Sameer Bajaj, a Product Manager & Software Builder. Explore more developer tools at sameerbajaj.com/tools.
📄 License
Licensed under the Apache License, Version 2.0. See LICENSE for details.
Available Tools
16 toolsauthor_getBRead-only
Fetch a public Goodreads author page. Required: author_id.
Inputs: author_id (required).
book_getBRead-only
Fetch a public Goodreads book page. Required: book_id.
Inputs: book_id (required).
contextARead-only
Get API domain context: resource taxonomy, auth requirements, query tips, and unique capabilities. Call this first.
Inputs: no named parameters.
enrichCDestructive
Resolve a title or Goodreads book ID to metadata suitable for syncing into Notion.
Inputs: csv, yes, args, json, +19 more.
goodreads-search_booksCRead-only
Search public Goodreads book pages. Required: q.
Inputs: q (required).
importBDestructive
Import data from a JSONL file by issuing POST requests for each record. Each line must be a valid JSON object. Failed records are logged to stderr but do not stop the import.
Inputs: input (required), csv, yes, args, +19 more.
review_get-shelfBRead-only
Fetch a public Goodreads user shelf page. Required: user_id. Optional: shelf.
Inputs: user_id (required), shelf.
shelf_auth_checkCDestructive
Validate Goodreads write authentication.
Inputs: csv, yes, json, agent, +16 more.
shelf_rateCDestructive
Set a Goodreads rating for a book.
Inputs: rating (required), csv, yes, args, +19 more.
shelf_setCDestructive
Mark a book as to-read, currently-reading, or read.
Inputs: shelf (required), csv, yes, args, +23 more.
shelf_unrateBDestructive
Remove your Goodreads rating for a book.
Inputs: csv, yes, args, json, +18 more.
shelf_unshelveCDestructive
Remove a book from your Goodreads shelves.
Inputs: csv, yes, args, json, +18 more.
sqlARead-only
Run read-only SQL against local database. Use for ad-hoc analysis, aggregations, and joins across synced resources. Requires sync first.
Inputs: query (required).
syncADestructive
Sync data from the API into a local SQLite database. Supports resumable incremental sync (only fetches new data since last sync) and full resync. Once synced, use the 'search' command for instant full-text search.
Exit codes & warnings: Resources the API denies access to (HTTP 403, or HTTP 400 with an access-policy body) are reported as warnings rather than failing the run. In --json mode each is emitted as a {"event":"sync_warning",...} line carrying status, reason, and message fields, and a final {"event":"sync_summary",...} aggregates the run.
Exit 0 when at least one resource synced and no resource flagged in the spec as critical (x-critical: true) failed; non-critical failures emit {"event":"sync_warning","reason":"exit_policy_default_changed", ...} so callers can detect that a partial failure was tolerated. Pass --strict to exit non-zero on any per-resource failure. Exit is always non-zero when every selected resource failed, regardless of --strict.
Inputs: db, csv, yes, full, +24 more.
workflow_archiveADestructive
Archive fetches all syncable resources from the API and stores them in a local SQLite database. Supports incremental sync (only new data since last run) and full resync. After archiving, use 'search' for instant full-text search.
Inputs: db, csv, yes, full, +18 more.
workflow_statusBRead-only
Show local archive status and sync state for all resources
Inputs: db, csv, yes, json, +17 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Most tools target distinct Goodreads resources or actions, but sync and workflow_archive are near-duplicates: both fetch API resources into a local SQLite database with incremental/full resync. enrich also overlaps somewhat with book_get, so an agent cannot reliably distinguish the intended choice from descriptions alone.
Tool names mix noun_verb (author_get, book_get, shelf_rate), verb_noun (workflow_archive), single-word commands (context, sync, sql), a hyphenated namespace (goodreads-search_books), and an internal hyphen (review_get-shelf). They are readable but do not follow a predictable convention.
At 16 tools, the set is just above the ideal 3–15 range and feels slightly heavy, especially with the duplicate sync/workflow_archive pair and a separate workflow_status tool. The count is not extreme, but the redundancy inflates the surface.
Core read, search, shelf-write, and local sync/SQL operations are present, but there are notable gaps: no standalone review retrieval/write, no author search, and no current-user/profile tool. The sync and workflow_archive descriptions also reference a 'search' command that is not exposed as a tool, leaving a dead end.
Maintenance
Related MCP Connectors
Unofficial Gutendex MCP — wraps Gutendex API for Project Gutenberg books (free, no auth)
MCP-сервер для поиска русскоязычных книг, получения карточек и кандидатов для рекомендаций.
Books MCP — wraps Open Library API (free, no auth)
MCP server for Project Gutenberg: 78,000+ public-domain ebooks with full plain-text retrieval.
Related MCP Servers
- AlicenseAqualityBmaintenanceA read-only MCP server for Goodreads that enables LLMs to search for books, retrieve detailed book info with ratings and reviews, and explore recommendations, series, and author bibliographies using public data sources without requiring authentication.1210MIT
- AlicenseNot gradedqualityCmaintenanceSelf-hosted MCP server for searching and discovering books using Anna's Archive and Goodreads datasets, enabling full-text search, ISBN/md5 lookup, similarity matching, and optional download URL retrieval.12 npm4MIT
- AlicenseAqualityBmaintenanceMCP server in Go to search and download books, papers, comics and more from Library Genesis — three focused tools, one static binary, no account required.433MIT
- AlicenseNot gradedqualityCmaintenanceA Go MCP server for inspecting and safely operating Audiobookshelf libraries.1MIT