Readwise Enhanced Mcp

---

status: published category: mcp-server author: arnaldo-delisio published_npm: true npm_package: readwise-mcp-enhanced published_directories: [] production_url: null last_active: 2026-01-26

Readwise MCP Enhanced

一款全面的模型上下文协议（MCP）服务，将 Readwise Reader 文档管理与完整的 Readwise highlights 功能整合在一起。适用于 Claude Desktop、Continue 及所有兼容 MCP 的 AI 工具。采用 TypeScript 构建，具备高级文本处理、智能内容控制和上下文优化响应等功能。

🚀 项目简介

首个统一型 MCP，整合了：

• 完整的 Readwise Reader API - 保存、管理和搜索文档
• 完整的 Readwise Highlights API - 访问所有高亮、书籍和每日回顾
• AI 驱动的文本处理 - 智能分词并提取内容
• 上下文优化 - 在保留完整功能的同时减少 94% 的令牌用量
• 智能内容控制 - 通过高级筛选和分页，防止上下文膨胀

功能相当于官方 Readwise MCP，但效率更高、功能更全面。兼容所有 MCP 客户端。

---

✨ 主要功能

📚 增强型 Reader 管理

• 智能内容提取：支持分页、关键词筛选和长度限制
• AI 驱动的文本处理：自动修复合并词语的分词问题
• 性能控制：内置高开销操作的警告和使用指导
• 灵活筛选：可按位置、类别、标签、日期和自定义条件筛选

🎯 完整的高亮生态

• 每日回顾：间隔重复学习系统
• 高级搜索：支持字段专属查询和相关性评分
• 书籍管理：提供完整元数据、高亮数量和筛选功能
• 导出与备份：批量分析高亮并增量同步
• 手动创建：支持添加带完整元数据的高亮

⚡ 生产级表现

• 上下文优化：令牌用量减少 94%（25,600 → 1,600 个令牌）
• 双 API 架构：无缝整合 v2（高亮）和 v3（Reader）
• 结果数量不限：没有人为限制，只需为每个条目高效提供数据
• 符合 MCP 协议：支持规范的日志记录、错误处理和速率限制

---

🛠️ 安装

选项 1：NPX - 无需安装！（推荐）

无需安装！任何 MCP 客户端都会使用 npx 自动下载并运行此软件包。

选项 2：全局 NPM 安装

npm install -g readwise-mcp-enhanced

选项 3：从源代码安装

git clone https://github.com/arnaldo-delisio/readwise-mcp-enhanced.git
cd readwise-mcp-enhanced
npm install
npm run build

🔧 配置

适用于任何兼容 MCP 的工具

1. 获取 Readwise 令牌： https://readwise.io/access_token

2. 添加到 MCP 客户端配置中：

   Claude Desktop：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

   Continue IDE 扩展：

   • 添加到 Continue 配置文件中

   其他 MCP 工具：

   • 按照相应工具的 MCP 服务配置说明操作

   选项 A - 使用 npx（推荐）：

   {
     "mcpServers": {
       "readwise-mcp-enhanced": {
         "command": "npx",
         "args": ["readwise-mcp-enhanced"],
         "env": {
           "READWISE_TOKEN": "your_readwise_access_token_here"
         }
       }
     }
   }
   

   选项 B - 通过 npm 全局安装：

   {
     "mcpServers": {
       "readwise-mcp-enhanced": {
         "command": "readwise-mcp-enhanced",
         "env": {
           "READWISE_TOKEN": "your_readwise_access_token_here"
         }
       }
     }
   }
   

   选项 C - 从源代码安装：

   {
     "mcpServers": {
       "readwise-mcp-enhanced": {
         "command": "node",
         "args": ["/path/to/readwise-mcp-enhanced/dist/index.js"],
         "env": {
           "READWISE_TOKEN": "your_readwise_access_token_here"
         }
       }
     }
   }
   

3. 重启 MCP 客户端（Claude Desktop、Continue 等）

---

📖 可用工具（共 13 个）

📚 Reader 工具（6 个）- 增强版

readwise_save_document

保存文档并全面控制元数据。

{
  "url": "https://example.com/article",
  "tags": ["ai", "productivity"],
  "location": "later",
  "category": "article"
}

readwise_list_documents

⭐ 已通过智能内容控制增强

{
  "withFullContent": true,
  "contentMaxLength": 10000,
  "contentStartOffset": 0,
  "contentFilterKeywords": ["AI", "machine learning"],
  "limit": 10
}

智能内容参数：

• contentMaxLength：限制每篇文档的内容长度（默认：50,000 个字符）
• contentStartOffset：从指定位置开始提取（分页）
• contentFilterKeywords：仅提取包含关键词的章节
• 昂贵操作警告

readwise_update_document

更新文档元数据（标题、作者、摘要、位置等）

readwise_delete_document

从 Reader 库中删除文档

readwise_list_tags

获取所有文档标签

readwise_topic_search

⭐ 已通过 AI 驱动的文本处理增强

• 使用正则表达式搜索标题、摘要、笔记和标签
• 自动进行词语分割，以便更好地匹配
• 在内容中分散查找关键词

---

🎯 高亮工具（7 个）- 新增

readwise_list_highlights

使用高级筛选条件列出高亮：

{
  "book_id": 12345,
  "highlighted_at__gt": "2024-01-01T00:00:00Z",
  "page_size": 100
}

readwise_get_daily_review

获取间隔重复高亮：

{
  "review_id": 168844911,
  "highlights": [
    {
      "text": "Strategic wisdom quote...",
      "title": "The Art of War",
      "author": "Sun Tzu"
    }
  ]
}

readwise_search_highlights

⭐ 支持按字段查询的高级搜索：

{
  "textQuery": "strategy tactics",
  "fieldQueries": [
    {
      "field": "document_title",
      "searchTerm": "Art of War"
    }
  ],
  "limit": 20
}

readwise_list_books

获取包含高亮元数据的图书：

{
  "category": "books", 
  "last_highlight_at__gt": "2024-01-01T00:00:00Z"
}

readwise_get_book_highlights

获取指定图书的所有高亮：

{
  "bookId": 53827741
}

readwise_export_highlights

批量导出，用于分析和备份：

{
  "updatedAfter": "2024-01-01T00:00:00Z",
  "includeDeleted": false
}

readwise_create_highlight

手动添加带元数据的高亮：

{
  "highlights": [
    {
      "text": "Important insight...",
      "title": "Book Title",
      "author": "Author Name",
      "note": "My thoughts on this",
      "category": "books"
    }
  ]
}

---

🎯 上下文优化

减少 94% 的令牌用量，同时保留全部功能：

工具	优化前	优化后	节省
列出高亮（32 项）	~25,600 个令牌	~1,600 个令牌	94%
每日回顾（5 项）	~5,000 个令牌	~400 个令牌	92%
列出图书（10 项）	~8,000 个令牌	~600 个令牌	93%

优化字段：

• 高亮：仅包含 id、text、note、book_id
• 图书：仅包含 id、title、author、category、num_highlights
• 搜索：仅包含 text、book、author、score

---

🧠 AI 驱动的功能

智能词语分割

自动修正常见的文本提取问题：

• whatyou → what you
• fromdissatisfaction → from dissatisfaction
• timeago → time ago

智能内容处理

• 对 YouTube 转录文本按句子分块
• 在内容中分散筛选关键词
• 根据上下文提取文本，并保留正确的空格

高级搜索算法

• 多字段搜索，并对相关性进行评分
• 基于导出的全面搜索，效果等同于官方 MCP
• 按字段筛选（标题、作者、文本、笔记、标签）

---

📊 技术架构

双 API 客户端系统

// Seamless API switching
v2 API: Highlights, books, daily review, export
v3 API: Reader documents, tags, search

上下文高效设计

• 每项仅包含最少数据，结果数量不限
• 针对大模型优化响应，便于高效解析
• 结构化 JSON 保留完整的推理能力

适用于生产环境

• 采用 ES Module 标准，并提供规范的 TypeScript 定义
• 符合 MCP 协议的日志记录和错误处理
• 全面的速率限制机制和优雅降级

---

⚙️ API 覆盖范围

Readwise Reader API（v3）

• ✅ 文档：保存、列出、更新、删除
• ✅ 标签：列出和筛选
• ✅ 内容：通过控制选项智能提取
• ✅ 搜索：增强的主题搜索

Readwise Highlights API（v2）

• ✅ 高亮：列出、创建、搜索、导出
• ✅ 图书：列出并支持元数据和筛选
• ✅ 每日回顾：间隔重复系统
• ✅ 高级搜索：按字段查询

---

🔐 身份验证与安全

• 单个令牌：使用一个 Readwise 令牌访问两个 API
• 环境变量：通过 READWISE_TOKEN 安全存储令牌
• 不暴露令牌：不会通过 MCP 客户端或工具界面暴露令牌

---

📈 速率限制

• Reader API：每分钟 20 个请求（默认），每分钟 50 个请求（CREATE/UPDATE）
• Highlights API：遵循 Readwise 标准限制，并自动处理 retry-after
• 智能处理：对 429 响应处理 “Retry-After” 标头

---

🚀 使用示例

智能内容提取

// Paginate through large document
readwise_list_documents({
  withFullContent: true,
  contentMaxLength: 5000,
  contentStartOffset: 0,
  contentFilterKeywords: ["machine learning", "AI"]
})

全面搜索

// Search across documents and highlights
readwise_search_highlights({
  textQuery: "productivity habits",
  fieldQueries: [
    { field: "document_author", searchTerm: "James Clear" }
  ],
  limit: 10
})

每日学习工作流

// Get daily review for spaced repetition
readwise_get_daily_review()

// Search related highlights for deeper study
readwise_search_highlights({
  textQuery: "from daily review topics",
  limit: 20
})

---

📦 依赖项

{
  "@modelcontextprotocol/sdk": "^1.0.0",
  "dotenv": "^16.3.0", 
  "node-html-parser": "^7.0.1",
  "wordsninja": "^1.0.0"
}

重要新增项：用于 AI 驱动的分词的 wordsninja

---

🔄 从 Basic Reader MCP 迁移

此统一 MCP 完全向后兼容。所有现有 Reader 工具均可照常使用，同时新增 7 个 Highlights 工具。

没有破坏性变更——只有更强大的功能和更出色的性能。

---

🌟 为什么选择此 MCP？

与官方 Readwise MCP 相比

• ✅ 更节省上下文（减少 94%）
• ✅ 统一界面（Reader + Highlights）
• ✅ 智能内容控制（分页、筛选）
• ✅ AI 驱动的文本处理
• ✅ 结果数量不限，且输出简洁

与 Basic Reader MCP 相比

• ✅ 完整的 Highlights 生态系统（新增 7 个工具）
• ✅ 高级搜索功能
• ✅ 可用于生产环境的性能
• ✅ 上下文优化

---

📄 许可证

MIT

---

🙏 致谢

在 edricgan/Readwise-Reader-MCP 的基础上构建，并进行了大量增强：

• 增强的 Reader 功能，支持智能内容控制
• 完整的 Highlights 集成，与官方 MCP 相当
• AI 驱动的文本处理，支持分词
• 上下文优化，提升生产效率
• 统一架构，无缝整合双 API

这标志着该项目从基础文档管理全面发展为功能完备、可用于生产环境的 Readwise 平台。 🚀