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:
{
"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="archive") # skipSearch across everything: Find all content on a topic — run both in parallel.
reader_search_documents(query="spaced repetition")
readwise_search_highlights(vector_search_term="spaced repetition")Quiz on a recent read: Find a finished document, get its content and highlights.
reader_list_documents(location="archive", limit=10, response_fields=["title", "author", "summary", "word_count"])
reader_get_document_details(document_id="<id>")
reader_get_document_highlights(document_id="<id>")Catch up on RSS: Browse feed items, surface the best ones, mark the rest as seen.
reader_list_documents(location="feed", limit=20, response_fields=["title", "author", "summary", "word_count", "site_name"])
reader_bulk_edit_document_metadata(documents=[{"document_id": "<id1>", "seen": true}, {"document_id": "<id2>", "seen": true}])
reader_move_documents(document_ids=["<id>"], location="later")Save and annotate: Save a URL, highlight key passages, tag and organize.
reader_create_document(url="https://example.com/article", tags=["research"])
reader_create_highlight(document_id="<id>", html_content="<p>Key passage here</p>", note="This connects to...")
reader_add_tags_to_document(document_id="<id>", tag_names=["important"])Build a reading recap: See what you've finished and highlighted recently.
reader_list_documents(location="archive", updated_after="2025-03-10T00:00:00Z", response_fields=["title", "author", "word_count", "reading_progress"])
reader_get_document_highlights(document_id="<id>")
readwise_list_highlights(highlighted_at_gt="2025-03-10T00:00:00Z", page_size=50)