readwise-mcp

What this skill does

# Readwise MCP

Use the Readwise MCP tools to access the user's Readwise highlights and Reader documents. Readwise has two products:

- **Readwise** — highlights from books, articles, podcasts, and more. Includes daily review and spaced repetition.
- **Reader** — a read-later app for saving and reading articles, PDFs, EPUBs, RSS feeds, emails, tweets, and videos.

## Setup

Add the Readwise MCP server to your client's configuration:

```json
{
  "readwise": {
    "type": "http",
    "url": "https://mcp2.readwise.io/mcp"
  }
}
```

The server handles authentication via OAuth — the user will be prompted to authorize on first use.

## Tool Reference

All tools are prefixed with `mcp__readwise__`. Each tool name maps directly to a Readwise or Reader API action.

## Reader Tools

### Searching documents

```
reader_search_documents(query="spaced repetition")
```

Hybrid search (semantic + keyword) across all saved documents. Combine with filters to narrow results:

```
# Search articles saved for later
reader_search_documents(query="machine learning", category_in=["article"], location_in=["later", "shortlist"])

# Search by author
reader_search_documents(query="AI agents", author_search="Simon Willison")

# Search within a date range
reader_search_documents(query="transformers", published_date_gt="2024-01-01")

# Search by tags
reader_search_documents(query="productivity", tags_in=["research"])
```

Other filters: `title_search`, `summary_search`, `note_search`, `url_search`, `source_search`, `document_id`, `limit` (default 20, max 100).

### Browsing documents

```
# List 10 most recent inbox items with minimal fields
reader_list_documents(location="new", limit=10, response_fields=["title", "author", "summary", "word_count", "category", "saved_at"])

# Archived articles with a specific tag
reader_list_documents(location="archive", tag=["research"], category="article")

# Unseen inbox items
reader_list_documents(location="new", seen=false)

# RSS feed items
reader_list_documents(location="feed", limit=20, response_fields=["title", "author", "summary", "site_name"])

# Get a specific document by ID
reader_list_documents(id="<document_id>")

# Paginate through results
reader_list_documents(location="later", limit=10, page_cursor="<cursor_from_previous_response>")
```

Locations: `new` (inbox), `later`, `shortlist`, `archive`, `feed`. When the user says "inbox", use `new`. Only use `feed` when the user explicitly asks about RSS/feeds.

Use `response_fields` to limit returned data and save tokens. The `id` field is always included. Available fields: `url`, `title`, `author`, `source`, `category`, `location`, `tags`, `site_name`, `word_count`, `reading_time`, `created_at`, `updated_at`, `published_date`, `summary`, `image_url`, `content`, `source_url`, `notes`, `parent_id`, `reading_progress`, `first_opened_at`, `last_opened_at`, `saved_at`, `last_moved_at`, `html_content`, `is_deleted`.

Tip: unseen documents have `first_opened_at=null`. Mark as seen via `reader_bulk_edit_document_metadata`.

### Reading and highlighting

```
# Get full document details including Markdown content
reader_get_document_details(document_id="<id>")

# Get all highlights on a document
reader_get_document_highlights(document_id="<id>")

# Create a highlight — html_content must match the document's HTML exactly
# Get the HTML via reader_list_documents with response_fields=["html_content"]
reader_create_highlight(document_id="<id>", html_content="<p>The exact passage to highlight</p>")

# Highlight with a note and tags
reader_create_highlight(document_id="<id>", html_content="<p>Key insight</p>", note="Connects to spaced repetition", tags=["review", "concept"])
```

### Saving documents

```
# Save a URL — Reader scrapes it automatically
reader_create_document(url="https://example.com/article")

# Save with metadata and tags
reader_create_document(url="https://example.com", title="Great Article", tags=["research", "ai"], notes="Recommended by Alice")

# Save raw Markdown content (provide a unique URL as identifier)
reader_create_document(title="Meeting Notes", markdown="# Notes from today...", url="https://me.com#notes-march-2025")
```

### Organizing

```
# Move documents between locations (max 50 per call)
reader_move_documents(document_ids=["<id1>", "<id2>"], location="archive")

# Bulk mark documents as seen
reader_bulk_edit_document_metadata(documents=[{"document_id": "<id>", "seen": true}])

# Bulk update metadata
reader_bulk_edit_document_metadata(documents=[{"document_id": "<id>", "title": "Better Title", "tags": ["ai", "research"]}])
```

Note: `reader_move_documents` and `reader_bulk_edit_document_metadata` share a rate limit of 20 calls/minute. Batch document IDs into fewer calls.

### Tags

```
# List all tags
reader_list_tags()

# Add tags to a document
reader_add_tags_to_document(document_id="<id>", tag_names=["important", "research"])

# Remove tags from a document
reader_remove_tags_from_document(document_id="<id>", tag_names=["old-tag"])

# Add tags to a highlight
reader_add_tags_to_highlight(document_id="<id>", highlight_document_id="<hid>", tag_names=["concept"])

# Remove tags from a highlight
reader_remove_tags_from_highlight(document_id="<id>", highlight_document_id="<hid>", tag_names=["old-tag"])

# Set notes on a highlight (pass null to clear)
reader_set_highlight_notes(document_id="<id>", highlight_document_id="<hid>", notes="My updated note")
```

### Exporting

```
# Export all documents as a ZIP of Markdown files (async — returns export_id)
reader_export_documents()

# Delta export — only docs updated since last export
reader_export_documents(since_updated="2024-01-01T00:00:00Z")

# Poll for completion
reader_get_export_documents_status(export_id="<id>")
```

Poll `reader_get_export_documents_status` until `status` is `"completed"`, then use the `download_url`.

## Readwise Tools

### Searching highlights

```
# Semantic search across all highlights
readwise_search_highlights(vector_search_term="learning techniques")

# Search with full-text filter on a specific field
readwise_search_highlights(vector_search_term="memory", full_text_queries=[{"field_name": "document_title", "search_term": "psychology"}])
```

Full-text query fields: `document_author`, `document_title`, `highlight_note`, `highlight_plaintext`, `highlight_tags`.

### Browsing highlights

```
# List 20 most recent highlights
readwise_list_highlights(page_size=20)

# Highlights from a specific book
readwise_list_highlights(book_id=12345)

# Highlights from the last month
readwise_list_highlights(highlighted_at_gt="2025-02-01T00:00:00Z")

# Paginate
readwise_list_highlights(page_size=100, page=2)
```

### Creating and editing highlights

```
# Create a highlight (matched to a book by title/author, or goes into "Quotes")
readwise_create_highlights(highlights=[{"text": "The key insight here", "title": "Book Title", "author": "Author Name"}])

# Create multiple highlights at once
readwise_create_highlights(highlights=[{"text": "First quote", "title": "Book A"}, {"text": "Second quote", "title": "Book B", "note": "Great point"}])

# Update a highlight
readwise_update_highlight(highlight_id=12345, note="New note", add_tags=["concept", "review"], color="blue")

# Delete a highlight
readwise_delete_highlight(highlight_id=12345)
```

Colors: `yellow`, `blue`, `pink`, `orange`, `green`, `purple`.

### Daily review

```
# Get today's spaced repetition review
readwise_get_daily_review()
```

Returns highlights selected by the algorithm plus a URL for interactive review.

## Example Workflows

**Triage the inbox:** List recent saves, read each one, decide what's worth the user's time.
```
reader_list_documents(location="new", limit=10, response_fields=["title", "author", "summary", "word_count", "category", "saved_at"])
reader_get_document_details(document_id="<id>")
reader_move_documents(document_ids=["<id>"], location="later")     # worth reading
reader_move_documents(document_ids=["<id>"], location="a