Skip to main content
Glama

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

Add Goodreads to Claude

Claude Code

claude mcp add --transport http goodreads https://goodreads-mcp-chi.vercel.app/oauth/mcp
claude mcp login goodreads

Cursor

Add Goodreads to Cursor

Codex

codex mcp add goodreads --url https://goodreads-mcp-chi.vercel.app/oauth/mcp
codex mcp login goodreads

To keep the library on your machine, run npx -y @organized-chaos/goodreads-mcp instead. Configuration is in Run locally.

IMPORTANT

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

List shelves found in RSS or an imported library

get_reading_list

Read a shelf with an optional result limit

get_currently_reading

Read the currently-reading shelf

get_recently_read

Return recently completed books

reading_stats

Calculate counts, ratings, pages, and pace, optionally by year

reading_brief

Create a fact-only, shareable Markdown reading summary

search_library

Search your own library by title, author, or ISBN

get_book

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 codex

The 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:

  1. Open Profile and derive GOODREADS_USER_ID from the digits after /user/show/ in the address bar.

  2. Open My Books, choose a shelf, scroll to the bottom, and find its RSS link.

  3. Parse GOODREADS_RSS_KEY from the link in memory, without opening, printing, or logging the secret-bearing URL.

  4. 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-mcp

You 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-mcp

Codex

# ~/.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 goodreads

Cursor

Add Goodreads to Cursor

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%3D

Codex

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 goodreads

Manual 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 with Vercel

Deploy a multi-user server to Vercel

Deploy with Vercel

For a manual deployment:

  1. Fork or clone this repository and run pnpm install.

  2. Install the Supabase integration from the Vercel Marketplace and keep the DATABASE_URL it provides. That URL is the transaction pooler (port 6543). The hosted server connects with pg. It does not use Neon. When the integration also sets POSTGRES_URL_NON_POOLING (session mode, port 5432 on the same pooler), schema changes use that URL. Otherwise they use DATABASE_URL.

  3. Set BETTER_AUTH_URL to the production origin and create three independent secrets: BETTER_AUTH_SECRET, a base64-encoded 32-byte GOODREADS_CREDENTIAL_KEY, and CRON_SECRET.

  4. Deploy. pnpm build runs pnpm db:migrate first. That applies every file in migrations/ in order, each in its own transaction, and records the filename in schema_migrations. A later build skips files that are already recorded, including preview builds that point at the same database. When neither POSTGRES_URL_NON_POOLING nor DATABASE_URL is set, the build logs Skipping 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.

  5. Connect MCP clients to https://YOUR_DOMAIN/oauth/mcp. vercel.json registers a daily cron at /api/cron/purge-unused. Confirm the job is listed for the project. Vercel calls it with Authorization: Bearer $CRON_SECRET. If Deployment Protection is enabled, allow Vercel Cron to reach that path.

  6. 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 build

pnpm 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 connection

See 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

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A 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.
      12
      10
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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