readwise-mcp

Readwise MCP

使用 Readwise MCP 工具访问用户的 Readwise 高亮和 Reader 文档。Readwise 有两款产品：

• Readwise — 来自书籍、文章、播客等内容的高亮。包含每日复习和间隔重复。
• Reader — 一款稍后阅读应用，可保存和阅读文章、PDF、EPUB、RSS 订阅、电子邮件、推文和视频。

设置

将 Readwise MCP 服务添加到客户端的配置中：

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

服务通过 OAuth 处理身份验证——首次使用时，系统会提示用户授权。

工具参考

所有工具均以 mcp__readwise__ 为前缀。每个工具名称都直接对应一个 Readwise 或 Reader API 操作。

Reader 工具

搜索文档

reader_search_documents(query="spaced repetition")

在所有已保存的文档中进行混合搜索（语义搜索 + 关键词搜索）。结合筛选条件缩小结果范围：

# 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"])

其他筛选条件：title_search、summary_search、note_search、url_search、source_search、document_id、limit（默认值为 20，最大值为 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>")

位置：new（收件箱）、later、shortlist、archive、feed。用户提到“收件箱”时，使用 new。只有用户明确询问 RSS/订阅源时，才使用 feed。

使用 response_fields 限制返回的数据，以节省 token。始终会包含 id 字段。可用字段：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。

提示：未读文档的 first_opened_at=null。通过 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"]}])

注意：reader_move_documents 和 reader_bulk_edit_document_metadata 共用每分钟 20 次调用的速率限制。将多个文档 ID 合并到较少的调用中。

标签

# 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>")

轮询 reader_get_export_documents_status，直到 status 为 "completed"，然后使用 download_url。

Readwise 工具

搜索高亮

# 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"}])

全文查询字段：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)

颜色：yellow、blue、pink、orange、green、purple。

每日复习

# Get today's spaced repetition review
readwise_get_daily_review()

返回算法选出的高亮，以及用于交互式复习的 URL。

工作流示例

整理收件箱： 列出最近保存的内容，逐一阅读，并判断哪些内容值得用户花时间。

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

全面搜索： 查找某个主题的所有内容——并行运行两项搜索。

reader_search_documents(query="spaced repetition")
readwise_search_highlights(vector_search_term="spaced repetition")

测验近期阅读内容： 查找一篇已读完的文档，获取其内容和高亮。

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>")

补看 RSS： 浏览订阅源内容，挑选优质内容，并将其余内容标记为已读。

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")

保存并批注： 保存 URL，为关键段落添加高亮、标签并进行整理。

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"])

生成阅读回顾： 查看近期读完并添加过高亮的内容。

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)