goodreads

README

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

Verify:

goodreads doctor
goodreads --help

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.

Documentation

Overview

Package goodreads provides a command-line tool and Model Context Protocol (MCP) server for Goodreads book discovery, metadata extraction, and authenticated shelf/rating write-back.

Full documentation, interactive web tools, and canonical project guides: https://sameerbajaj.com/tools/goodreads-cli/