# Readwise Reader — how to use (mcp.ai)

Connect your Readwise Reader account and use 6 tools for bookmarks straight from your AI agent. Connect with your own API key. Save, list, organize, update, and delete documents in a Readwise Reader library.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_readwise_reader?ms=1787291460000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `readwise_reader_bulk_update_documents`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/readwise_reader`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/readwise_reader/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/readwise_reader/bulk/update/documents` — Partially update up to 50 Reader documents in one request and return a success or error result for every document.
  - body: { updates: object[] }
- `POST https://api.mcp.ai/api/readwise_reader/delete/document` — Permanently delete one Reader document by its ID.
  - body: { document_id: string }
- `POST https://api.mcp.ai/api/readwise_reader/list/documents` — List, filter, incrementally sync, or fetch a specific Reader document. Returns one page and a cursor for the next page.
  - body: { tags?: string[], limit?: integer, category?: string, location?: string, document_id?: string, next_cursor?: string, updated_after?: string, with_html_content?: boolean, with_raw_source_url?: boolean }
- `POST https://api.mcp.ai/api/readwise_reader/list/tags` — List tags in the connected Reader library, returning one page and a cursor for the next page.
  - body: { next_cursor?: string }
- `POST https://api.mcp.ai/api/readwise_reader/save/document` — Save a URL or supplied HTML as a document in the connected Reader library, with optional metadata, location, and tags. Returns the Reader document ID needed by update and delete tools.
  - body: { url: string, html?: string, tags?: string[], notes?: string, title?: string, author?: string, summary?: string, category?: string, language?: string, location?: string, image_url?: string, saved_using?: string, published_date?: string, should_clean_html?: boolean }
- `POST https://api.mcp.ai/api/readwise_reader/update/document` — Partially update supported fields on one Reader document by ID; omitted fields remain unchanged.
  - body: { seen?: boolean, tags?: string[], notes?: string, title?: string, author?: string, summary?: string, category?: string, language?: string, location?: string, image_url?: string, document_id: string, published_date?: string }

## Example prompts
- "What can I do in Readwise Reader?"
- "Show me a summary of my Readwise Reader account"

## More
- Page: https://mcp.ai/readwise_reader
- Agent spec (llms.txt): https://mcp.ai/readwise_reader/llms.txt
- Postman collection: https://mcp.ai/readwise_reader/postman.json