Goodreads (Read + Write)

Full Goodreads integration: read shelves, search books, get details/reviews via RSS, and write actions (rate, shelf, review, edit dates, progress) via Playwright browser automation. Use when user asks about reading list, books, ratings, or wants to update their Goodreads.

Goodreads Skill

Full read + write access to Goodreads via RSS feeds and Playwright browser automation.

Scripts

# Read-only (RSS + scraping, no login required)
R=scripts/goodreads-rss.py

# Write (Playwright browser automation, requires one-time login)
W=scripts/goodreads-write.sh

Setup

See references/SETUP.md for installation and first-time login instructions.

Quick start:

# Install dependencies
pip install playwright playwright-stealth
playwright install chromium

# Login to Goodreads (one-time, opens browser)
./scripts/goodreads-write.sh login

User Configuration

Replace <USER_ID> with your Goodreads user ID in all commands below.

How to find your user ID: Go to your Goodreads profile page. The URL will be like: goodreads.com/user/show/12345678-yourname — the number is your user ID.

For write commands with RSS verification, set:

export GOODREADS_USER_ID="<YOUR_USER_ID>"

---

Read Commands

1. View shelf

python3 $R shelf <USER_ID> --shelf <shelf> [--limit N] [--sort <sort>]

--shelf	Meaning
currently-reading	Currently reading
read	Already read
to-read	Want to read
<custom>	Custom shelf

--sort	Meaning
date_read	Date finished (default for read)
date_added	Date added to shelf
rating	Personal rating
title	Book title
author	Author name
avg_rating	Average Goodreads rating

Examples:

python3 $R shelf <USER_ID> --shelf currently-reading
python3 $R shelf <USER_ID> --shelf read --limit 20 --sort date_read
python3 $R shelf <USER_ID> --shelf to-read --limit 50
python3 $R shelf <USER_ID> --shelf read --limit 200 --sort rating

Fields returned: title, author, book_id, isbn, user_rating (0–5), average_rating, date_read, date_added, review, shelves, description (300 chars), published, book_url

2. Recent activity

python3 $R activity <USER_ID> [--limit N]

Returns: books added, marked read, reviews written...

3. Search books

python3 $R search "<query>" [--limit N]

python3 $R search "Jared Diamond" --limit 10
python3 $R search "atomic habits" --limit 5

Returns: book_id, title, author, book_url

4. Book details

python3 $R book <book_id>

Returns: title, author, average_rating, rating_count, review_count, description, isbn, published, genres, image_url

5. Book reviews

python3 $R reviews <book_id> [--limit N]

⚠️ Reviews are rendered via React — available count may be limited.

---

Write Commands

Requires one-time login. Run $W login first. Session persists for weeks/months.

1. Check login status

$W status

2. Rate a book

$W rate <book_id> <stars>

Stars: 1–5 (integer)

$W rate 40121378 5        # Rate Atomic Habits 5 stars

3. Change shelf

$W shelf <book_id> <shelf_name>

shelf_name	Display	Notes
to-read	Want to Read
currently-reading	Currently Reading
read	Read

Output includes "verified": true/false — RSS auto-confirms after action.

$W shelf 186190 read                # Move to "Read"
$W shelf 186190 currently-reading   # Move to "Currently Reading"

4. Start reading

$W start <book_id>

Shortcut for shelf <book_id> currently-reading. RSS verified.

5. Finish reading

$W finish <book_id>

Shortcut for shelf <book_id> read. RSS verified.

6. Edit (dates, review, rating)

$W edit <book_id> [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--stars N] [--review "text"]

Uses the /review/edit/ page — can edit everything in one command.

⚠️ Book must be shelved first (use $W shelf or $W start).

Examples:

$W edit 186190 --start-date 2025-01-15 --end-date 2025-02-20
$W edit 186190 --stars 4
$W edit 186190 --review "Great book, highly recommend."
$W edit 186190 --start-date 2025-03-01 --end-date 2025-03-08 --stars 4 --review "Updated review"

7. Write/Update review

$W review <book_id> "<text>"

8. Update reading progress

$W progress <book_id> <page_or_percent>

⚠️ Book must be on currently-reading shelf.

$W progress 13618551 150    # Reading page 150

---

Sample Workflows

"What am I currently reading?"

python3 $R shelf <USER_ID> --shelf currently-reading

"Find books about Japanese history"

python3 $R search "Japanese history" --limit 10
# → get book_id → python3 $R book <id> for details

"I just finished Forrest Gump, rate 4 stars, read from 3/1 to 3/8"

$W finish 186190
$W edit 186190 --stars 4 --start-date 2025-03-01 --end-date 2025-03-08

"Start reading Atomic Habits"

$W start 40121378

---

Output Format

All commands return JSON:

{
  "success": true,
  "action": "edit",
  "book_id": "186190",
  "changes": ["start_date=2025-03-01", "end_date=2025-03-08", "stars=4"],
  "message": "Updated: start_date=2025-03-01, end_date=2025-03-08, stars=4"
}

Limitations

Feature	Status
Read shelf	✅ RSS, max 200 books/request
Activity feed	✅ RSS
Search books	✅ Scraping
Book details	✅ Scraping + JSON-LD
Reviews	⚠️ Limited scraping
Rate (1-5 stars)	✅
Change shelf (+ RSS verify)	✅
Start/Finish reading	✅
Write/edit review	✅
Edit reading dates	✅
Update progress	✅ (requires currently-reading)
Session persistence	✅ (stealth, weeks/months)
Remove from shelf	❌ Not supported
Custom shelves (write)	❌ Only 3 main shelves

Note: Goodreads may change its UI → scripts may break. If errors occur, check selectors. Anti-bot: Uses playwright-stealth + --disable-blink-features=AutomationControlled.