// 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.
| name | goodreads |
| description | 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. |
| metadata | {"openclaw":{"category":"reading","requires":{"bins":["python3"]},"notes":{"api":"Goodreads official API deprecated Dec 2020. Read uses RSS feeds + HTML scraping. Write uses Playwright browser automation with stealth mode."}}} |
Full read + write access to Goodreads via RSS feeds and Playwright browser automation.
# 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
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
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>"
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
python3 $R activity <USER_ID> [--limit N]
Returns: books added, marked read, reviews written...
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
python3 $R book <book_id>
Returns: title, author, average_rating, rating_count, review_count, description, isbn, published, genres, image_url
python3 $R reviews <book_id> [--limit N]
⚠️ Reviews are rendered via React — available count may be limited.
Requires one-time login. Run
$W loginfirst. Session persists for weeks/months.
$W status
$W rate <book_id> <stars>
Stars: 1–5 (integer)
$W rate 40121378 5 # Rate Atomic Habits 5 stars
$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"
$W start <book_id>
Shortcut for shelf <book_id> currently-reading. RSS verified.
$W finish <book_id>
Shortcut for shelf <book_id> read. RSS verified.
$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 shelfor$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"
$W review <book_id> "<text>"
$W progress <book_id> <page_or_percent>
⚠️ Book must be on
currently-readingshelf.
$W progress 13618551 150 # Reading page 150
python3 $R shelf <USER_ID> --shelf currently-reading
python3 $R search "Japanese history" --limit 10
# → get book_id → python3 $R book <id> for details
$W finish 186190
$W edit 186190 --stars 4 --start-date 2025-03-01 --end-date 2025-03-08
$W start 40121378
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"
}
| 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.