Raindrop.io MCP Server

Raindrop.io MCP 服务

通过简单的 MCP 服务将 Raindrop.io 连接到 AI 助手。使用自然语言整理、搜索和管理书签。

Raindrop.io 现在也为 Pro 用户提供托管的 Streamable HTTP MCP 端点（https://api.raindrop.io/rest/v2/ai/mcp），目前处于 Beta 阶段。如果其托管工具集能够满足需求，请使用该端点；如果需要本地 stdio、可自托管的 HTTP，以及额外的资料库管理工具，请使用此软件包。

功能

• 创建、更新和删除集合与书签
• 按标签、域名、类型、日期等搜索书签
• 管理标签（列出、重命名、合并、删除）
• 阅读书签中的高亮内容
• 批量编辑集合中的书签
• 检查失效链接和重复项，并管理回收站

工具

• diagnostics - 服务诊断信息和资料库健康指标
• collection_list - 以平面列表形式列出所有集合
• get_collection_tree - 以层级视图显示集合，并提供完整的面包屑路径
• collection_manage - 创建、更新或删除集合
• bookmark_search - 使用筛选条件、标签和分页进行高级搜索
• bookmark_manage - 创建、更新或删除书签
• get_raindrop - 按 ID 获取单个书签
• list_raindrops - 分页列出某个集合中的书签
• get_suggestions - 为 URL 或书签提供 AI 驱动的整理建议（标签/集合）
• suggest_tags - 使用 AI 辅助分析，根据书签元数据推荐相关标签
• bulk_edit_raindrops - 批量更新、移动或移除指定集合中的书签
• tag_manage - 重命名、合并或删除标签
• highlight_manage - 创建、更新或删除高亮内容
• library_audit - 扫描资料库中的失效链接、重复项和未加标签的项目
• empty_trash - 永久清空回收站（需要确认）
• cleanup_collections - 移除空集合（需要确认）
• remove_duplicates - 查找并移除重复书签，并通过安全确认流程执行

安装

快速开始（单行命令）

工具	单行命令
Gemini CLI	gemini extensions install https://github.com/adeze/raindrop-mcp
Codex CLI	codex mcp add raindrop -- npx -y @adeze/raindrop-mcp
Claude Code	claude mcp add raindrop -- npx -y @adeze/raindrop-mcp
GitHub Copilot	gh copilot config mcp add raindrop -- npx -y @adeze/raindrop-mcp
Vercel Skills	npx skills add adeze/raindrop-mcp

注意：对于通过 npx 添加 MCP 服务的工具，必须在 shell 环境或工具的环境配置中设置 RAINDROP_ACCESS_TOKEN 环境变量。

Vercel Skills（npx skills）

本项目兼容 Vercel Skills 系统。所需的清单文件均已包含：

• manifest.json：标准 MCP 服务定义清单。
• SKILL.md：用于 Agent 发现的标准化技能说明。
• mcp.json：MCP 客户端和注册表的根配置文件。

将此服务添加到本地技能目录：

npx skills add adeze/raindrop-mcp --global

要将此项目提交到 Vercel Skills Registry，请提交 Pull Request，将此仓库 URL 添加到注册表中。

Claude Desktop（MCPB）

从 GitHub Release 下载最新的 raindrop-mcp.mcpb，并将其添加到 Claude Desktop：

• Releases：https://github.com/adeze/raindrop-mcp/releases

在 Claude Desktop 中添加此捆绑包并设置此环境变量：

• RAINDROP_ACCESS_TOKEN（从 Raindrop.io 集成设置中获取）

NPX（CLI）

将 API 令牌设为环境变量并运行：

export RAINDROP_ACCESS_TOKEN=YOUR_RAINDROP_ACCESS_TOKEN
npx @adeze/raindrop-mcp

手动配置 MCP（mcp.json）

将以下内容添加到 MCP 客户端配置中：

{
  "servers": {
    "raindrop": {
      "type": "stdio",
      "command": "npx",
      "args": ["@adeze/raindrop-mcp@latest"],
      "env": {
        "RAINDROP_ACCESS_TOKEN": "YOUR_RAINDROP_ACCESS_TOKEN"
      }
    }
  }
}

HTTP

bun run start:http 会在 127.0.0.1:3002 上提供 /mcp；设置 HTTP_PORT 可更改端口。HTTP 工具使用服务端的 RAINDROP_ACCESS_TOKEN。Host 和 Origin 检查可防止 DNS 重绑定，但不会对调用方进行身份验证。若要远程访问，请在本地回环端点前配置经过身份验证的反向代理。

要求

• 一个 Raindrop.io 账户
• 一个 Raindrop.io API 访问令牌：https://app.raindrop.io/settings/integrations

支持

• 问题反馈：https://github.com/adeze/raindrop-mcp/issues

发布

此仓库仅支持使用 semantic-release 进行发布。

发布流程

• 验证通过后，推送到 master 会通过 .github/workflows/publish.yml 触发发布。
• 发布任务会串行运行；只有发布任务会获得仓库写入权限和 OIDC 权限。
• semantic-release 会分析 Conventional Commit 消息、计算下一个版本、更新 CHANGELOG.md、在 GitHub 上打标签并创建发布，同时发布到 npm。
• 发布准备期间，.releaserc.json 会同步 manifest.json、mcp.json 和 gemini-extension.json，然后构建 raindrop-mcp.mcpb，使 GitHub Release 包含此捆绑包。

预发布试运行

• 在 GitHub Actions 中，选择 Validate and Publish → Run workflow，并在 master 上运行。保持启用 dry_run 以预览发布；禁用后则会运行 semantic-release 发布流程。
• 此操作会验证语义化版本计算、注册表身份验证和发布流程，不会实际发布。

必需的机密

• GitHub Actions 会提供 GITHUB_TOKEN，用于自动发布。

npm 可信发布

• npm 发布通过 GitHub Actions OIDC 可信发布进行配置。
• 可信发布者的工作流文件名必须设为 publish.yml，包括手动试运行。
• 标准 CI 发布流程不需要 NPM_TOKEN。

合并前的本地验证

使用 Node 24.15+ 和 Bun 1.4.3+。已发布的服务要求 Node 22.19+。 Vite+ 1.1 通过 vite.config.ts 管理 lint、格式化、类型检查、测试和打包；Bun 仍是包管理器。

bun install --frozen-lockfile
bun run check
bun run test
bun run test:coverage
bun run docs

bun run build 会运行 vp pack，保留 build/index.js、build/server.js、 源映射和打包后的依赖。测试会先进行构建，以便从干净的检出版本运行包检查。 bun run dev 和 bun run dev:http 保留 Bun 的服务监视模式；bunx vp run dev 运行相同的脚本。vp dev 会启动 Vite Web 服务，并非此 MCP 服务的开发命令。

服务使用 TypeScript 7.0.2。TypeDoc 和 OpenAPI 类型生成目前需要 TypeScript 6 编译器 API，因此 tooling/compiler-api 保留了自己的 TypeScript 6.0.3 依赖。请从根目录安装； bun run docs 仍会生成现有文档。

bun run update:deps 会刷新依赖，同时确保覆盖率与 Vite+ 内置的 Vitest 5.0.3 保持一致。 升级 Vite+ 时，请同时更新这些固定版本。迁移后移除了生成的 clearMocks: false 设置， 因为使用 Vitest 5 默认值时，同样有 61 项测试通过。覆盖率检查的文件与 Vitest 4 相同， 共 16 个；没有放宽任何阈值或排除项。原始构建使用 Bun，因此无需 tsdown 兼容性设置。

未使用的 Java/Axios 生成器依赖栈已移除；类型化的 openapi-fetch 仍是共享客户端。 目前测试过的两个 OpenAPI 生成器都需要较旧的 TypeScript 编译器 API：Hey API 0.99.0 在显示 CLI 帮助之前就会在 TypeScript 7 下失败。隔离且经过测试的生成器避免了对身份验证、 速率限制和缓存行为的改动。

发布工具仍会拉取受 GHSA-vfj7-8cjw-p6xm 影响的 braces 3.0.3；目前尚未发布修复版本。此依赖不会包含在服务包中。不要向发布工具 提供不可信的 glob 模式。

重大变更和已审查的修复

• 删除书签、集合、标签或高亮，以及批量移除，现在都需要 confirm: true。清理工具保留 现有的预览流程。
• HTTP 绑定到 127.0.0.1；OAuth 回调要求匹配、未过期且仅使用一次的浏览器状态。 远程访问需要经过身份验证的代理。
• 批量移动、更新和移除使用源集合的 API 端点。书签更新会保留 collectionId； 仅更改其他字段时，省略 URL/title。集合 0 表示“全部”，不能用于批量修改； -1 表示“未分类”。
• 标签使用上游搜索运算符，并保留分页和总数。集合路径不再依赖 API 排序； 修改会使受影响的书签、搜索和集合计数缓存失效。
• 不会重试永久性上游错误。资源模板使用 MCP SDK；不再声明不受支持的资源订阅。
• MCPB 包含打包后的运行时代码，而不是开发依赖。环境文件、日志和本地 Codex 状态均会排除。

这些修复解决了 PR #52 和 issues #54/#55 中的实质性问题。 较早的 SDK v1/Zod 3 迁移已由此 SDK v2 配置取代。无需替换框架：现有 SDK API 和共享服务 辅助函数消除了冗余代码。Raindrop 实时修改和 OAuth 提供商登录仍需手动验证。

提交消息示例

• fix: handle empty tag merge payload
• feat: add collection path filter
• feat!: remove deprecated search parameter

常规发布时，请勿手动提升版本、推送发布标签或运行手动 npm 发布命令。

📋 近期改进（v2.4.x）

智能整理与层级结构

• AI 建议：新增 get_suggestions 工具，利用 Raindrop 的 API 和 MCP Sampling 提供整理建议。
• 集合树：get_collection_tree 工具提供包含完整面包屑路径的层级视图。
• 批量移动：为 bulk_edit_raindrops 添加 move 操作，方便高效整理资料库。
• 分页支持：为 list_raindrops 和 bookmark_search 统一添加分页功能，支持大型资料库。

安全与质量

• 确认逻辑：破坏性工具（empty_trash、cleanup_collections）现在需要明确确认。
• 命名规范统一：所有工具现在都使用一致的 snake_case 命名规范。
• CI/CD 流水线：增强了 GitHub Actions，支持自动 lint、类型检查和跨传输测试。
• 代码质量：建立了 ESLint 和 Prettier 配置，便于维护开发。

📋 先前更新（v2.3.3）

高级清理与资料库审查

📋 先前更新（v2.3.2）

MCP 资源链接实现

• 采用符合当前 MCP SDK 最佳实践的现代 resource 内容。
• 高效访问数据：工具返回轻量级链接，而非完整负载。
• 性能更佳：客户端仅在需要时获取完整的书签/集合数据。
• 与动态资源系统（mcp://raindrop/{id}）无缝集成。

SDK 与 API 更新

• 更新至本仓库支持的最新 MCP SDK。
• 采用描述更完善的现代工具注册方式。
• 修复 API 端点和路径参数。
• 所有核心工具均已全面可用。

工具优化

• 书签/集合列表采用高效利用资源的响应方式。
• 通过 mcp://collection/{id} 和 mcp://raindrop/{id} 动态访问资源。
• 列表负载更轻，客户端体验更佳。
• 完全符合官方 SDK 模式的 MCP 规范。

服务层改进

• 提取通用辅助函数，减少代码量。
• 统一错误处理和响应处理。
• 通过泛型处理器增强类型安全性。
• 集中构建端点。

测试改进

• 加强 MCP 工具执行的端到端测试覆盖。
• 扩展集成测试，覆盖真实场景中的客户端流程。

MCP 2.0 准备工作（批量操作）

• 为 MCP 2.0 批量操作工作流和工具打下基础。

OAuth（即将推出）

• 采用基于 OAuth 的身份验证流程，简化设置，无需手动提供令牌。

注意

对于最近几次构建给大家带来的影响，我们深表歉意。感谢大家的耐心等待和反馈。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。