Readwise MCP Server

Readwise MCP 服务

一个用于 Readwise 的 Model Context Protocol (MCP) 服务，可让 AI 助手访问你保存的文章、书籍、划线和文档。

功能

• 书籍与文章：浏览你收藏的书籍和文章
• 划线：访问所有划线内容
• 搜索：在整个 Readwise 资料库中查找内容
• 最近内容：快速获取你最近保存的项目
• 标签管理：使用标签整理和筛选内容
• 高级搜索：按作者、日期、标签等条件强力筛选
• 阅读进度：跟踪阅读状态和完成百分比
• 批量操作：高效地一次管理多份文档
• 内容管理：在资料库中保存、更新和删除内容
• 视频支持：访问并操作保存在 Readwise Reader 中的视频
• 速率限制：智能处理 API 限制，防止请求受限
• 传输选项：支持 stdio（Claude Desktop）和 SSE（网页）传输方式
• MCP 合规性：完全符合协议规范，并妥善处理 request_id

安装

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 Readwise MCP：

npx -y @smithery/cli install @iamalexander/readwise-mcp --client claude

手动安装

1. 获取 Readwise API 令牌：

   • 登录你的 Readwise 账户
   • 前往 https://readwise.io/access_token 生成 API 令牌
   • 复制令牌以备后用

2. 从 npm 安装：

   npm install -g readwise-mcp
   

3. 或克隆并构建：

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

4. 配置 API 密钥：

   # Run the setup wizard
   npm run setup
   
   # Or start with the API key directly
   readwise-mcp --api-key YOUR_API_KEY
   

Docker 支持

如果你更喜欢使用 Docker：

1. 创建配置目录：

   mkdir -p ~/.readwise-mcp
   

2. 构建并运行：

   docker build -t readwise-mcp .
   docker run -p 3001:3001 -e READWISE_API_KEY=your_key readwise-mcp
   

使用示例

连接到 Claude 后，可以通过以下问题充分利用 Readwise 中的知识：

• “查找我关于‘vibes-first programming’和美学 IDE 的划线”
• “我保存了哪些关于 Claude Code 隐藏复活节彩蛋的内容？”
• “显示所有标记为‘AI’和‘productivity’的文章”
• “我的待读列表里有哪些还没开始读的内容？”
• “查找我过去 3 个月保存的 Paul Graham 的文章”
• “显示我已读完的书籍”
• “将这篇文章保存到我的 Readwise：https://example.com/interesting-article”
• “给那篇关于量子计算的文章添加‘must-read’标签”
• “我那本关于机器学习的书读到什么进度了？”

视频相关示例

• "显示我在 Readwise 中保存的所有 YouTube 视频"
• "我对那个关于 TypeScript 的视频做了哪些高亮？"
• "我对那个 AI 会议视频的当前播放进度是多少？"
• "在我的库中查找提到 'machine learning' 的视频"
• "在 TypeScript 教程的 23:45 处创建一个高亮，备注为 'Important pattern'"
• "在那个 AI 安全视频的 15 分钟处，讲者说了什么？"
• "显示我昨天保存的编程教程的文字记录"

功能文档

基本功能

浏览内容

• 列出书籍和文章：分页获取你 Saved 的书籍
• 获取高亮：通过筛选选项访问你所有的已高亮段落
• 搜索内容：在整个库中进行全文搜索
• 获取最近内容：快速访问你最新保存的项目

标签管理

使用标签整理你的内容：

• 列出所有标签：获取你库中的所有标签
• 获取文档的标签：查看特定文档上的标签
• 更新标签：替换文档上的所有标签
• 添加特定标签：向文档添加单个标签
• 移除特定标签：从文档中移除一个标签
• 批量打标签：一次性为多个文档应用标签

高级搜索

强大的筛选选项，帮助你精确找到所需内容：

• query：搜索文本
• category：按内容类型筛选（书籍、文章等）
• tags：按标签筛选（逗号分隔）
• author：按作者筛选
• title：按标题筛选
• location：按位置筛选（new、later、archive、feed）
• dateFrom 和 dateTo：ISO 8601 格式的日期范围
• sortBy：排序字段（created_at、updated_at、title、author）
• sortOrder：排序方向（asc、desc）

阅读进度跟踪

跟踪你的阅读状态和进度：

• 获取阅读进度：查看任何文档的当前进度
• 更新阅读进度：设置状态、百分比和页码
• 获取阅读列表：按阅读状态筛选

阅读状态：

• not_started：尚未开始阅读
• in_progress：正在阅读
• completed：已完成阅读

视频功能

访问并互动你保存在 Readwise Reader 中的视频：

视频列表和详情

• 列出所有视频：浏览来自 YouTube、Vimeo 和其他平台的视频
• 获取带文字记录的视频详情：访问完整的元数据和时间同步的文字记录

视频高亮

• 创建带时间戳的高亮：标记视频中的重要时刻
• 获取视频高亮：获取某个视频的所有高亮，按时间戳排序

视频播放进度

• 更新播放进度：保存你当前的位置以便稍后继续
• 获取播放进度：从你上次离开的地方继续

文字记录访问的工作原理

视频文字记录功能：

1. 从视频的 HTML 内容中提取时间同步的文字记录
2. 解析时间戳和文本对
3. 将文字记录作为带时间戳的片段数组返回

这使你可以：

• 在视频中搜索特定内容
• 在精确的时刻创建高亮
• 直接跳转到重要点
• 使用准确的时间上下文引用视频内容

内容管理

保存、更新和删除内容：

• 保存新内容：将 URL、文章或自定义内容添加到你的库中
• 更新文档：修改标题、作者、摘要、标签等
• 删除文档：移除内容（带安全确认）

批量操作

高效地一次管理多个文档：

• 批量保存：保存多个 URL/内容项目
• 批量更新：更新多个文档
• 批量删除：移除多个文档
• 批量打标签：为多个文档应用标签

安全确认

所有批量操作和删除操作都需要显式确认，以防止意外数据丢失：

• 单文档删除：需要确认参数
• 批量操作：需要特定确认字符串

这些确认充当“人在回路”的安全机制。

API 状态

随时查看 API 状态和速率限制信息。

可用工具

该服务提供 30 个工具，用于与你的 Readwise 库交互：

核心工具

• get_highlights：通过筛选和分页获取高亮
• get_books：从你的库中获取书籍
• get_documents：从你的库中获取文档
• search_highlights：按查询搜索高亮
• get_tags：列出你库中的所有标签
• get_recent_content：获取最近保存的内容

标签管理

• document_tags：获取、更新、添加或移除文档上的标签
• bulk_tags：将标签应用到多个文档

阅读进度

• get_reading_progress：获取特定文档的进度
• update_reading_progress：更新阅读状态和进度
• get_reading_list：按阅读状态筛选文档

高亮管理

• create_highlight：创建新高亮
• update_highlight：修改现有高亮
• delete_highlight：移除高亮
• create_note：为高亮添加笔记

搜索工具

• advanced_search：强大的多参数搜索
• search_by_tag：按标签查找内容
• search_by_date：按日期范围查找内容

视频工具

• get_videos：列出你库中的视频
• get_video：获取带转录文本的视频详情
• create_video_highlight：创建带时间戳的高亮
• get_video_highlights：获取某个视频的所有高亮
• update_video_position：保存播放位置
• get_video_position：获取已保存的播放位置

文档管理

• save_document：将新内容保存到库
• update_document：修改文档元数据
• delete_document：移除文档

批量操作

• bulk_save_documents：保存多个文档
• bulk_update_documents：更新多个文档
• bulk_delete_documents：删除多个文档

可用资源

MCP 资源为大模型客户端提供直接数据访问：

• books（readwise://books）：你的 Readwise 库中的书籍列表
• recent-highlights（readwise://highlights/recent）：你库中的最近高亮
• tags（readwise://tags）：你的 Readwise 库中所有标签的列表

可用提示词

• readwise_highlight：处理来自 Readwise 的高亮

  • 支持摘要、分析、查找关联和生成问题
  • 包含健壮的错误处理和参数校验
  • 以读者友好的方式格式化高亮

• readwise_search：搜索并处理来自 Readwise 的高亮

  • 提供带来源信息的格式化搜索结果
  • 优雅地处理 API 错误，并给出用户友好的消息
  • 包含对必需参数的校验

演示和测试

该仓库包含演示文件，帮助你测试和探索功能：

演示文件

• demo/test-connection.html：测试与服务的基本连接
• demo/mcp-demo.html：涵盖所有功能的综合 UI
• demo/video-features.html：视频功能的专用界面
• demo/enhanced-transcript-features.html：高级转录文本功能

运行测试

# Run the full test suite
npm test

# Run automated inspector tests
npm run test-inspector

# Test without a real API key (mock mode)
npm run test-mock

使用 MCP Inspector 测试

# Test with stdio transport (default)
./scripts/inspector.sh

# Test with SSE transport
./scripts/inspector.sh -t sse -p 3001

# Enable debug mode
./scripts/inspector.sh -d

集成

Claude Desktop

添加到你的 Claude Desktop 配置：

• Linux：~/.config/Claude/claude_desktop_config.json
• Mac：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "readwise": {
      "command": "readwise-mcp",
      "env": {
        "READWISE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor

添加到项目中的 .cursor/mcp.json：

{
  "mcpServers": {
    "readwise": {
      "command": "readwise-mcp",
      "env": {
        "READWISE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Code

通过命令行安装：

claude mcp add readwise-mcp --transport http https://server.smithery.ai/@IAmAlexander/readwise-mcp/mcp

或使用 JSON 配置格式：

{
  "mcpServers": {
    "readwise-mcp": {
      "type": "http",
      "url": "https://server.smithery.ai/@IAmAlexander/readwise-mcp/mcp"
    }
  }
}

部署

Smithery

通过 Smithery CLI 安装：

npx @smithery/cli install @iamalexander/readwise-mcp --client claude

或在 Smithery Registry 上找到它。

Railway（一键部署）

1. 点击上方按钮，或前往 Railway
2. 连接你的 GitHub 仓库
3. 添加环境变量：READWISE_API_KEY
4. 部署！

Render

1. 在 Render 上创建一个新的 Web Service
2. 连接你的 GitHub 仓库
3. Render 会自动检测 render.yaml
4. 添加环境变量：READWISE_API_KEY
5. 部署！

Docker

docker build -t readwise-mcp .
docker run -p 3001:3001 -e READWISE_API_KEY=your_key readwise-mcp

故障排除

Token 问题

如果你遇到身份验证问题：

1. 在 https://readwise.io/access_token 验证你的 Readwise API token 是否仍然有效
2. 通过删除已存储的凭据来重置身份验证：

   rm ~/.readwise-mcp/credentials.json
   

3. 重新启动并再次尝试连接

连接问题

如果服务无法连接：

1. 确保服务正在运行（如果是手动启动的）
2. 检查端口 3001 是否未被其他应用占用
3. 重启你的 AI 客户端（Claude Desktop、Cursor 等）

速率限制

该服务内置了速率限制。如果你遇到速率限制错误：

1. 等待几分钟后再重试
2. 降低请求频率
3. 检查响应中的速率限制标头

视频相关问题

1. 缺少转录文本：并非所有视频都有转录文本。YouTube 视频通常支持得最好。
2. 转录文本质量：转录文本来自视频平台，可能包含错误。
3. 时间戳不一致：不同平台使用不同格式；API 会在可能的情况下进行规范化。
4. 播放位置未更新：确保同时提供 position 和 duration 参数。

隐私与安全

• 你的 Readwise API token 安全地存储在你的本地机器上
• 只有在明确请求时才会访问你的 Readwise 数据
• 不会在 MCP 服务上永久存储任何数据
• 安全确认可防止意外数据丢失

开发

# Build the project
npm run build

# Run tests
npm test

# Start in development mode with auto-reload
npm run dev:watch

# Lint code
npm run lint

项目结构

• src/：主源代码
• test-scripts/：测试脚本和实用工具
• examples/：示例实现
• demo/：交互式 HTML 演示
• tests/：测试套件

贡献

发现了 bug？有功能想法？想让这个 MCP 服务变得更棒？欢迎并鼓励贡献！

如何贡献

1. Fork 此仓库（最好一边喝着你喜欢的饮品一边进行）
2. 创建你的功能分支（git checkout -b feature/my-amazing-idea）
3. 编写一些氛围优化的代码（RGB 注释可选，但会很受欢迎）
4. 提交你的更改（git commit -m 'Add mind-blowing feature'）
5. 推送到分支（git push origin feature/my-amazing-idea）
6. 打开一个 Pull Request，然后等待它被合并时多巴胺飙升的那一刻

所有贡献，无论大小、实用还是异想天开，都同样珍贵！

许可证

MIT 许可证

版权所有 (c) 2023 Alexander

特此免费授予任何获得本软件及相关文档文件（以下简称“软件”）副本的人，不受限制地处理本软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利，并允许向其提供软件的人这样做，但须符合以下条件：

上述版权声明和本许可声明应包含在软件的所有副本或实质性部分中。

本软件按“原样”提供，不附带任何形式的明示或暗示担保，包括但不限于对适销性、特定用途适用性和非侵权性的担保。在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论是在合同诉讼、侵权行为或其他方面，由软件或软件的使用或其他交易引起、产生或与之相关。