Skip to main content
Glama

Goodreads CLI (goodreads)

Go Reference Documentation License: Apache-2.0 Author Tools

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@latest

Verify:

goodreads doctor
goodreads --help

Related 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_count

Shelf 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 --json

Supported 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 --json

Manual auth also works:

export GOODREADS_COOKIE='_session_id2=...; other_cookie=...'
goodreads shelf auth-check --json

export GOODREADS_JWT='...'
goodreads shelf auth-check --json

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

  • --agent sets JSON, compact output, non-interactive mode, no color, and --yes.

  • --dry-run previews writes without sending them.

  • Mutating commands are grouped under shelf.

  • Write commands require --yes unless --dry-run is 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_id

MCP

Build the MCP server:

go build -o bin/goodreads-mcp ./cmd/goodreads-mcp

Manual 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 --json

Run 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/goodreads

Notes

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 tools
author_getB
Read-only

Fetch a public Goodreads author page. Required: author_id.

Inputs: author_id (required).

book_getB
Read-only

Fetch a public Goodreads book page. Required: book_id.

Inputs: book_id (required).

contextA
Read-only

Get API domain context: resource taxonomy, auth requirements, query tips, and unique capabilities. Call this first.

Inputs: no named parameters.

enrichC
Destructive

Resolve a title or Goodreads book ID to metadata suitable for syncing into Notion.

Inputs: csv, yes, args, json, +19 more.

goodreads-search_booksC
Read-only

Search public Goodreads book pages. Required: q.

Inputs: q (required).

importB
Destructive

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-shelfB
Read-only

Fetch a public Goodreads user shelf page. Required: user_id. Optional: shelf.

Inputs: user_id (required), shelf.

shelf_auth_checkC
Destructive

Validate Goodreads write authentication.

Inputs: csv, yes, json, agent, +16 more.

shelf_rateC
Destructive

Set a Goodreads rating for a book.

Inputs: rating (required), csv, yes, args, +19 more.

shelf_setC
Destructive

Mark a book as to-read, currently-reading, or read.

Inputs: shelf (required), csv, yes, args, +23 more.

shelf_unrateB
Destructive

Remove your Goodreads rating for a book.

Inputs: csv, yes, args, json, +18 more.

shelf_unshelveC
Destructive

Remove a book from your Goodreads shelves.

Inputs: csv, yes, args, json, +18 more.

sqlA
Read-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).

syncA
Destructive

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_archiveA
Destructive

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_statusB
Read-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

    C2.9/5.0

    Scored across 16 tools

    Disambiguation2/5

    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.

    Naming Consistency2/5

    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.

    Tool Count3/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    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
      C
      maintenance
      Self-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 npm
      4
      MIT