readwise-mcp

Readwise MCP (mcporter)

This skill is intentionally kept short. High-level workflows live in: skills/readwise-mcp/RECIPES.md.

Preflight

command -v mcporter && mcporter --version

Ensure you’re in the Clawdbot workspace root where config/mcporter.json lives.

Quick setup (first time)

# Add the server to the *project* config
mcporter config add readwise https://mcp2.readwise.io/mcp \
  --auth oauth \
  --description "Readwise MCP"

# Start OAuth login (will open a browser)
mcporter auth readwise --reset

Verify it works

mcporter list readwise --output json
mcporter call readwise.reader_list_tags --args '{}' --output json

Troubleshooting OAuth (common failure modes)

“Invalid OAuth state”

Cause: you approved in a stale browser tab (old auth attempt / old port).

Fix:

• Close old Readwise OAuth tabs.
• Re-run:

mcporter auth readwise --reset

Redirecting to an old port even after reset

Cause: browser session reuse.

Fix:

• Use Incognito/Private window.
• Or copy the new authorize URL into a fresh profile.

“Waiting for browser approval…” but you already approved

You must land on:

http://127.0.0.1:<PORT>/callback?code=...&state=...

If the redirect hits a different port, mcporter will keep waiting.

To find the expected port:

cat ~/.mcporter/credentials.json

Look for redirect_uris and ensure the browser redirect matches exactly.

Using the server

General pattern:

mcporter call readwise.<tool_name> --args '{...}' --output json

Notes:

• --args must be valid JSON (prefer single quotes in shell).
• For Reader locations: new = inbox, later, shortlist, archive, feed (RSS only).

Tool index (what’s available)

• readwise_search_highlights — search highlights (vector + optional field filters)
• reader_search_documents — search Reader documents (hybrid search)
• reader_create_document — save a URL or HTML into Reader
• reader_list_documents — list newest documents (and paginate)
• reader_get_document_details — fetch a document’s full Markdown content
• reader_get_document_highlights — fetch highlights for a document
• reader_list_tags — list tag names
• reader_add_tags_to_document / reader_remove_tags_from_document
• reader_add_tags_to_highlight / reader_remove_tags_from_highlight
• reader_set_document_notes / reader_set_highlight_notes
• reader_move_document — move between inbox/later/shortlist/archive
• reader_edit_document_metadata — edit metadata (including seen)
• reader_export_documents — export Reader docs as a ZIP

Quick examples (most-used)

1) Search highlights (idea-first / semantic)

mcporter call readwise.readwise_search_highlights \
  --args '{"vector_search_term":"incentives", "limit": 10}' \
  --output json

2) Search Reader documents (hybrid)

mcporter call readwise.reader_search_documents \
  --args '{"query":"MCP", "limit": 10}' \
  --output json

3) List newest docs in inbox (thin fields)

mcporter call readwise.reader_list_documents \
  --args '{
    "limit": 10,
    "location": "new",
    "response_fields":["title","author","url","category","location","created_at","tags"]
  }' \
  --output json

4) Get a document’s full content (markdown)

mcporter call readwise.reader_get_document_details \
  --args '{"document_id":"<id>"}' \
  --output json

Recipes

See: skills/readwise-mcp/RECIPES.md

Recipe names:

• Triage inbox (or Later fallback)
• Feed digest (last day/week) + mark as seen
• Quiz the user on a recently read archived document
• Recommendations (build a reading profile → pick next best doc)
• Library organizer (tagging + inbox-zero)

Shortlist semantics (important)

Readwise supports a shortlist location, but many people use it differently.

Default assumption (most users): inbox / later / archive

• “Shortlisting” means: add a shortlist tag AND move the doc to later.

Alternative setup: later / shortlist / archive

• “Shortlisting” means: move the doc to location=shortlist.

So: before applying any shortlisting action, confirm which setup the user uses. If unknown, assume the default (tag + move to later).

Safety / defaults

When a workflow proposes writes (tagging, moving, setting notes/seen), default to:

• show a read-only plan first (counts + which docs)
• ask for approval before applying changes