// How to use the Readwise MCP tools — access highlights, documents, and your entire reading library via MCP
Visualize your highlights and their connections in an interactive 2D graph
How to use the Readwise CLI — access highlights, documents, and your entire reading library from the command line
Access your Readwise highlights and Reader documents from the command line. Search, read, organize, and manage your entire reading library.
Analyze your reading history and tell you something surprising you don't know about yourself
Catch up on your RSS feed — highlights up top, full browse below
Triage Reader inbox one doc at a time with personalized pitches
| name | readwise-mcp |
| description | How to use the Readwise MCP tools — access highlights, documents, and your entire reading library via MCP |
Use the Readwise MCP tools to access the user's Readwise highlights and Reader documents. Readwise has two products:
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.
All tools are prefixed with mcp__readwise__. Each tool name maps directly to a Readwise or Reader API action.
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).
# 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.
# 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"])
# 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")
# 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.
# 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")
# 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.
# 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.
# 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)
# 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.
# Get today's spaced repetition review
readwise_get_daily_review()
Returns highlights selected by the algorithm plus a URL for interactive review.
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") # skip
Search 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)