Goodreads MCP
Provides tools to interact with Goodreads shelves and reading history, including listing shelves, getting currently reading, recently read books, reading stats, searching library, and fetching book details with enrichment from Open Library.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Goodreads MCP
Ask what to read next from your own Goodreads shelves and ratings. Your Goodreads password stays on Goodreads. The server reads RSS feeds and CSV exports you choose to share.
Clients: Claude, Claude Code, Cursor, Codex, and any other MCP client.
Try this: “Which books did I rate five stars, and what should I read next?”
Install
The hosted server takes about a minute. Add it, sign in, and paste your
Goodreads profile URL (the address containing /user/show/ and your numeric
id). Add the shelf RSS key only when your shelves are private. The key is
entered on the connect page and encrypted before storage. It is not sent as a
request header.
Hosted endpoint:
https://goodreads-mcp-chi.vercel.app/oauth/mcp
/mcp on this shared host is disabled and responds with HTTP 410. A health
check that does not open a database connection is at
/health.
Claude
Claude Code
claude mcp add --transport http goodreads https://goodreads-mcp-chi.vercel.app/oauth/mcp
claude mcp login goodreadsCursor
Codex
codex mcp add goodreads --url https://goodreads-mcp-chi.vercel.app/oauth/mcp
codex mcp login goodreadsTo keep the library on your machine, run
npx -y @organized-chaos/goodreads-mcp instead. Configuration is in
Run locally.
Goodreads retired its public API. This project does not scrape Goodreads, collect session cookies, or use private Goodreads APIs. RSS is limited to roughly the most recent 100 books on each shelf; import a CSV export for complete history.
Related MCP server: goodreads-mcp
Tools
Tool | Purpose |
| List shelves found in RSS or an imported library |
| Read a shelf with an optional result limit |
| Read the |
| Return recently completed books |
| Calculate counts, ratings, pages, and pace, optionally by year |
| Create a fact-only, shareable Markdown reading summary |
| Search your own library by title, author, or ISBN |
| Find a library book and enrich ISBN metadata through Open Library |
Run locally
Requirements: Node.js 20 or newer. The guided setup also requires a locally installed Google Chrome or Chromium browser.
Start with a real question
After connecting, copy one of these into your AI client:
“Create my reading brief for 2026 and make it ready to share.”
“Which books did I rate five stars, and what do they have in common?”
“Pick three books from my to-read shelf based on my favorite authors.”
“Which unfinished series should I return to?”
Set up your Goodreads connection
For a guided local setup, run the command for the AI client you use:
npx -y @organized-chaos/goodreads-mcp setup --client claude
# or
npx -y @organized-chaos/goodreads-mcp setup --client codexThe setup helper opens a temporary visible browser window. Sign in to
Goodreads yourself in that window, then press Enter in the terminal. It finds
your profile ID and RSS link locally, asks before changing your AI client's
configuration, and reports only whether each value was found. It never asks
for, reads, or stores your Goodreads password or session cookies. The browser
session is closed when setup finishes. Claude Code's user-scoped server is
written to ~/.claude.json. The RSS key is stored in that file and is not
passed on a process command line. Codex configuration is written to
~/.codex/config.toml. Both files are readable only by your user account.
The helper configures the hosted OAuth endpoint at
https://goodreads-mcp-chi.vercel.app/oauth/mcp. It does not write an RSS key
into that client config. Enter the key later on the OAuth connect page, where
it is encrypted before storage. If you do not want to use the guided helper,
the manual configuration below remains supported.
If you prefer to complete the connection manually, your only Goodreads credential work should still happen directly on Goodreads. The setup sequence is:
Open Profile and derive
GOODREADS_USER_IDfrom the digits after/user/show/in the address bar.Open My Books, choose a shelf, scroll to the bottom, and find its RSS link.
Parse
GOODREADS_RSS_KEYfrom the link in memory, without opening, printing, or logging the secret-bearing URL.Show the local destination and variable names, ask for confirmation, write the values, restart the MCP client, and verify the connection.
Browser control handles navigation; a local configuration tool handles the
write. The assistant should report only whether each value was found and
written—not the values themselves. If you are setting up manually, the user ID
is the numeric part of your profile URL. The RSS key is the value after key=
in the RSS link; leave it unset if the link has no key parameter.
The user ID is not sensitive. Treat the RSS key like a password. Keep it only in your local environment or your MCP client's secret configuration; never put the full RSS URL or key in source control, screenshots, chat, or command output. The key is optional when your Goodreads feeds are public.
Sign in to Goodreads yourself; never give an automation tool your password or ask it to read, export, or store session cookies. Once the RSS link is visible, the tool must not capture screenshots, browser snapshots, network logs, the current URL, or the link target. No particular browser or MCP client is required.
Set the values in the environment that launches your MCP client:
export GOODREADS_USER_ID=12345678
export GOODREADS_RSS_KEY=your-rss-key
npx -y @organized-chaos/goodreads-mcpYou can also set GOODREADS_CSV_PATH to a Goodreads library export for complete
local history. Restart your MCP client after changing environment variables.
Claude Code
claude mcp add goodreads \
--env GOODREADS_USER_ID=12345678 \
--env GOODREADS_RSS_KEY=your-rss-key \
-- npx -y @organized-chaos/goodreads-mcpCodex
# ~/.codex/config.toml
[mcp_servers.goodreads]
command = "npx"
args = ["-y", "@organized-chaos/goodreads-mcp"]
[mcp_servers.goodreads.env]
GOODREADS_USER_ID = "12345678"
GOODREADS_RSS_KEY = "your-rss-key"Connect to the hosted server
The shared deployment is goodreads-mcp-chi.vercel.app. Connect clients to its OAuth endpoint:
https://goodreads-mcp-chi.vercel.app/oauth/mcp
Sign in through your MCP client. On the connect page, paste your Goodreads
profile URL (for example https://www.goodreads.com/user/show/12345678-name)
and optional RSS key. The key is encrypted before storage. It is not written
into client config and is not sent as a request header. The OAuth provider
supports dynamic client registration, PKCE, refresh tokens, and
protected-resource metadata.
/health returns 503, with the missing variable names, until OAuth is
configured. It does not connect to Postgres.
Claude Code
claude mcp add --transport http goodreads https://goodreads-mcp-chi.vercel.app/oauth/mcp
claude mcp login goodreadsCursor
Cursor asks you to confirm the server, then starts the OAuth sign-in. The same install link as a deeplink:
cursor://anysphere.cursor-deeplink/mcp/install?name=goodreads&config=eyJ1cmwiOiJodHRwczovL2dvb2RyZWFkcy1tY3AtY2hpLnZlcmNlbC5hcHAvb2F1dGgvbWNwIn0%3DCodex
Codex does not publish a browser install link. Add the OAuth endpoint, then sign in:
codex mcp add goodreads --url https://goodreads-mcp-chi.vercel.app/oauth/mcp
codex mcp login goodreadsManual Codex config, with no Goodreads headers:
# ~/.codex/config.toml
[mcp_servers.goodreads]
url = "https://goodreads-mcp-chi.vercel.app/oauth/mcp"The guided setup command writes that URL, plus a Goodreads user ID header, and leaves the RSS key out. The config file is restricted to your user account.
Self-host the stateless endpoint
A deployment you control can still serve header-based /mcp for one Goodreads
account. That path stays available only when VERCEL_PROJECT_PRODUCTION_URL
is not one of the shared hosts above. Keep X-Goodreads-User-ID and the
optional X-Goodreads-RSS-Key in the client that talks to your own host. The
server removes the RSS key header before the MCP handler runs, so handler
logs do not include it. Do not point those headers at the shared deployment.
Deploy a multi-user server to Vercel
For a manual deployment:
Fork or clone this repository and run
pnpm install.Install the Supabase integration from the Vercel Marketplace and keep the
DATABASE_URLit provides. That URL is the transaction pooler (port 6543). The hosted server connects withpg. It does not use Neon. When the integration also setsPOSTGRES_URL_NON_POOLING(session mode, port 5432 on the same pooler), schema changes use that URL. Otherwise they useDATABASE_URL.Set
BETTER_AUTH_URLto the production origin and create three independent secrets:BETTER_AUTH_SECRET, a base64-encoded 32-byteGOODREADS_CREDENTIAL_KEY, andCRON_SECRET.Deploy.
pnpm buildrunspnpm db:migratefirst. That applies every file inmigrations/in order, each in its own transaction, and records the filename inschema_migrations. A later build skips files that are already recorded, including preview builds that point at the same database. When neitherPOSTGRES_URL_NON_POOLINGnorDATABASE_URLis set, the build logsSkipping database migrations: neither POSTGRES_URL_NON_POOLING nor DATABASE_URL is set.and continues, so CI and forks without a database still build. The log line names the variable that was used and does not include the connection string.Connect MCP clients to
https://YOUR_DOMAIN/oauth/mcp.vercel.jsonregisters a daily cron at/api/cron/purge-unused. Confirm the job is listed for the project. Vercel calls it withAuthorization: Bearer $CRON_SECRET. If Deployment Protection is enabled, allow Vercel Cron to reach that path.Open
/health. It returns 200 when those four variables are set and 503, naming any that are missing. It does not connect to Postgres.
The OAuth endpoint uses Better Auth for DCR, PKCE, refresh tokens, and protected-resource metadata. Goodreads RSS keys are encrypted before storage; CSV rows and the 15-minute RSS cache live in Postgres.
Vercel’s file route for api/auth/[...all].ts matches a single path segment,
so /api/auth/jwks is served directly and /api/auth/oauth2/register is not.
vercel.json rewrites /api/auth/:authPath* to that function. Leave the
rewrite in place; without it, dynamic client registration returns Vercel’s
platform 404 and MCP clients cannot connect.
Abuse controls
Routing Middleware (middleware.ts) rate limits /mcp, /oauth/mcp,
/api/auth/*, and /connect before the route runs when
ABUSE_MIDDLEWARE_SECRET, BETTER_AUTH_SECRET, or CRON_SECRET is set. It
marks that request so the route handler does not count it a second time. The
handlers apply the same limits when the mark is absent, including a stateless
deployment that has none of those secrets. Each route has a per-IP window and,
when the request carries one, a per-credential window. Credentials
are the Goodreads user id on /mcp, the bearer token on /oauth/mcp, and the
Better Auth session cookie or bearer token on /connect and /api/auth/*.
The limiter stores a SHA-256 digest of that credential. It does not store the
RSS key, access token, or session token. Anonymous sign-in
(/api/auth/sign-in/anonymous) and dynamic client registration
(/api/auth/oauth2/register) have stricter per-IP limits plus a global hourly
ceiling.
Limits are fixed windows. The shared counters live in abuse_rate_limits when
DATABASE_URL is set, so every instance enforces the same budget. A deployment
without DATABASE_URL keeps counters in memory for that instance only. The
deploy migration creates that table. Until it exists, OAuth, auth, and connect
return 503 and /mcp falls back to the in-memory counters.
Unauthenticated dynamic client registration stays enabled. MCP clients register
before the reader signs in, and turning that off breaks login for Claude,
Codex, and other clients that follow the MCP authorization spec. Registration
is throttled, and the daily cron deletes anonymous users who never connected a
library and OAuth clients that never received a token, refresh token, or
consent. Retention defaults to 24 hours for unused anonymous users and 7 days
for unused clients. Override them with ABUSE_ANONYMOUS_TTL_HOURS and
ABUSE_OAUTH_CLIENT_TTL_HOURS.
The numeric limits live in packages/server-vercel/src/abuse.ts.
Development
corepack enable
pnpm install
pnpm check
pnpm buildpnpm build runs pnpm db:migrate before the package builds. That command
applies migrations/*.sql when POSTGRES_URL_NON_POOLING or DATABASE_URL
is present and logs a skip line when neither is set.
Workspace layout:
packages/core RSS, CSV, library queries, stats, Open Library
packages/server-local stdio MCP server published as @organized-chaos/goodreads-mcp
packages/server-vercel OAuth, Postgres storage, and hosted library service
api/server.ts Stateless Vercel endpoint at /mcp (disabled on the shared host)
api/oauth-mcp.ts OAuth Vercel Streamable HTTP endpoint at /oauth/mcp
api/health.ts Config health check; does not open a database connectionSee AGENTS.md for an architecture and conventions brief, CONTRIBUTING.md for project boundaries, and SECURITY.md for reporting and data-handling details.
Privacy
The local server keeps your library and credentials on your machine. The
shared Vercel deployment stores the Goodreads identity, an encrypted RSS key,
imported CSV rows, and OAuth grants required to serve each account. Its
public /mcp path does not accept header credentials. A self-hosted
stateless endpoint receives the Goodreads identity and optional RSS key in
HTTPS request headers and does not persist them; it strips the RSS key header
before handler logging. Neither path receives your Goodreads password. RSS
responses may be cached for up to 15 minutes. When DATABASE_URL is set,
rate limiting also stores the client IP and a hash of the request credential.
Use the authenticated delete_account MCP tool to remove the Goodreads
profile, imported books, login user, sessions, and OAuth grants for that
account. Remove the connection in the MCP client so it discards its local
token.
Open Library receives ISBN queries when get_book performs enrichment. Review
the policies of Goodreads, Open Library, your database provider, Vercel, and
your MCP client before use.
Limitations and migration path
Goodreads RSS normally exposes only about 100 recent items per shelf.
Private profiles may need an RSS key or CSV-only mode.
Some CSV exports omit fields used by aggregate statistics.
If Goodreads retires RSS, the core data-source interface can support another provider. Hardcover is the intended migration candidate because it offers a documented GraphQL API and Goodreads import.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read-only MCP server for verified book recommendations and reading lists.
Read and update your Hardcover library, progress, lists, and goals. Sign in with Hardcover OAuth.
Reddit MCP — public Reddit data via the Atom/RSS feeds.
Related MCP Servers
- FlicenseBqualityFmaintenanceA CLI tool that integrates with Claude Desktop to allow users to retrieve their Goodreads library data through MCP.17-
- 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 gradedqualityDmaintenanceEnables searching for lawful, free-to-read books across multiple open catalogues and resolving access routes (download, read, borrow, preview) via MCP tools like search_books and resolve_access.MIT
- AlicenseAqualityAmaintenanceEnables an LLM to search and research Goodreads books, ratings, and reviews using public data, without login or writes.12179 PyPIGPL 3.0