/readwise-mcp

name: readwise-mcp
description: How to use the Readwise MCP tools — access highlights, documents, and your entire reading library via MCP

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 `dow