内容
以下是翻译后的文档：
· · · · · · · · · · · · · · · ·
· · · · · · · · · · · · · ·
____ _ ___ _ _ _ _______ _____ _____ ____ _____ ____
| _ \ / \ |_ _| \ | | |/ / ____| ____| ___| _ \| ____| __ \
| |_) | / _ \ | || \| | ' /| _| | _| | |_ | |_) | _| | /
| _ < / ___ \ | || |\ | . \| |___| |___| _| | __/| |___| _ \
|_| \_\/_/ \_\___|_| \_|_|\_\_____|_____|_| |_| |_____|_| \_\
· · · · · · · · · · · · · ·
· · · · · · · · · · · · · · · ·
<div align="center">
**适用于免费账户的 Raindrop.io MCP 服务器 — 真正移动书签。**
[](https://www.python.org/)
[](https://github.com/jlowin/fastmcp)
[](LICENSE)
[](https://developer.raindrop.io)
</div>
---
## 什么是 Raindrop.io？
[Raindrop.io](https://raindrop.io) 是一个书签管理器，使网页变得可收藏。保存任何内容 — 文章、视频、PDF、图片、链接 — 并将其组织成集合和子集合，添加标签，注释，并在需要时将其呈现出来。它运行在所有平台上，在所有地方同步，并且有一个涵盖大多数人所需功能的免费层。
如果你曾经丢失过链接，放弃过浏览器书签，或者希望你的稍后阅读队列能够回应 — Raindrop 就是答案。
Rainkeeper 将 Raindrop 连接到 Claude，为您的整个图书馆提供自然语言控制。
---
## 为什么选择 Rainkeeper？
现有 MCP 选项存在两个问题：
**官方 Raindrop.io MCP 服务器需要 Pro 订阅**（约 3 美元/月）。如果您处于免费层 — 涵盖了 Raindrop 的大部分功能 — 您无法使用它。
**社区替代方案（adeze/raindrop-mcp）存在一个严重的静默错误：** 集合移动操作无效。要求 Claude 将书签归档到集合中，API 调用返回 200 OK — 但书签仍然位于原处。根本原因是请求正文格式错误，Raindrop API 静默忽略。相同的错误破坏了所有批量移动操作。
Rainkeeper 解决了这两个问题。
| | Rainkeeper | 官方 MCP | 社区 MCP |
|---|:---:|:---:|:---:|
| 免费账户 | ✅ | ❌ 仅 Pro | ✅ |
| 集合移动有效 | ✅ | ✅ | ❌ 静默失败 |
| 子集合支持 | ✅ | — | ❌ |
| 批量操作 | ✅ | — | ✅（已损坏） |
| 可自我托管 | ✅ | ✅ | ✅ |
| 开源（MIT） | ✅ | — | ✅ |
---
## 修复
Raindrop.io REST API 对所有集合引用使用嵌套对象。发送平面整数被接受而无错误 — 并被静默忽略。
```json
// ✅ 正确 — Rainkeeper 发送的内容
PUT /raindrop/123
{"collection": {"$id": 456}}
// ❌ 静默忽略 — 社区 MCP 发送的内容
PUT /raindrop/123
{"collectionId": 456}
```
同样适用于批量操作：
```json
// ✅ 正确
PUT /raindrops/0
{"ids": [111, 222], "collection": {"$id": 456}}
// ❌ 返回 404 或静默失败
PUT /raindrops/0
{"ids": [111, 222], "collectionId": 456}
```
`RaindropClient` 在 HTTP 层强制执行正确的格式。工具从不向 API 传递原始整数 ID。一个规则，一个地方，始终正确。
---
## 快速入门
### 1. 获取您的令牌
Raindrop.io → **设置 → 集成 → 为开发者** → 创建应用 → 复制 **测试令牌**。免费账户包含。耗时 30 秒。
### 2. 安装
```bash
git clone https://github.com/simonives/rainkeeper.git
cd rainkeeper
pip install -e . # 或：uv pip install -e .
```
### 3. 配置
```bash
cp .env.example .env
# 打开 .env — 设置 RAINDROP_ACCESS_TOKEN=您的令牌
```
### 4. 注册到 Claude
<details>
<summary><strong>Claude 桌面版（macOS / Windows）</strong></summary>
将以下内容添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"rainkeeper": {
"command": "python",
"args": ["-m", "rainkeeper.server"],
"cwd": "/绝对路径/to/rainkeeper",
"env": {
"RAINDROP_ACCESS_TOKEN": "您的令牌"
}
}
}
}
```
重启 Claude 桌面版后保存。
</details>
<details>
<summary><strong>Claude CLI</strong></summary>
```bash
claude mcp add rainkeeper -- python -m rainkeeper.server
```
确保您的 `.env` 位于 `rainkeeper` 目录中并包含您的令牌。
</details>
### 5. 验证
询问 Claude： *"列出我的 Raindrop 集合。"*
您应该在几秒内看到您的集合。如果您收到身份验证错误，请验证您的配置中的令牌是否与 Raindrop 设置 → 集成中的令牌匹配。
---
## 工具
Rainkeeper 在五个领域暴露了 **17 个工具**。Claude 会自动选择正确的工具 — 文档字符串针对工具选择准确性进行了调整。
> **每个会话都以 `list_collections` 开头。** 您需要集合 ID 来移动或归档书签，而 Raindrop 不使用可预测的名称作为标识符。
### 集合
| 工具 | 功能 |
|---|---|
| `list_collections` | 所有集合和子集合 — id、title、parent_id、count |
| `get_collection` | 单个集合详情 |
| `create_collection` | 新集合；传递 `parent_id` 以嵌套在现有集合中 |
| `update_collection` | 重命名、重新着色或切换公共可见性 |
| `delete_collection` | 删除集合 — 内容移动到未分类 |
### 书签
| 工具 | 关键参数 | 备注 |
|---|---|---|
| `list_raindrops` | `collection_id`、`page`、`per_page`、`sort` | `0` = 所有，`-1` = 未分类 |
| `get_raindrop` | `raindrop_id` | 完整详情：标签、备注、类型、域名 |
| `create_raindrop` | `link`、`collection_id`、`title`、`tags`、`note` | 默认保存到未分类 |
| `update_raindrop` | `raindrop_id` + 任意字段 | 传递 `collection_id` 以移动 |
| `move_raindrop` | `raindrop_id`、`target_collection_id` | 显式移动 — 比更新更好的工具选择 |
| `delete_raindrop` | `raindrop_id` | 永久 |
### 批量操作
| 工具 | 功能 |
|---|---|
| `bulk_move_raindrops` | 将书签 ID 列表移动到目标集合 |
| `bulk_tag_raindrops` | 对书签列表应用标签（与现有标签合并） |
| `bulk_mark_important` | 加星或取消加星书签列表 |
| `bulk_delete_raindrops` | 永久删除书签列表 |
### 搜索
| 工具 | 备注 |
|---|---|
| `search_raindrops` | 默认搜索所有书签（`collection_id=0`）。支持完整的 Raindrop 搜索语法。 |
**搜索语法：
| 语法 | 示例 | 查找 |
|---|---|---|
| 单词 | `python` | 包含“python”的书签 |
| 短语 | `"machine learning"` | 精确短语匹配 |
| 标签 | `#ai` | 已标记为“ai”的书签 |
| 类型 | `type:article` | 仅文章（`article`、`video`、`image`、`document`、`audio`） |
| 排除 | `-draft` | 排除单词“draft” |
| 域名 | `site:github.com` | 来自特定域名的书签 |
| 无标签 | `#` | 无标签的书签 |
| 未分类 | `collection:unsorted` | 未分类的项目 |
| 加星 | `important:true` | 已加星 / 重要的书签 |
### 标签
| 工具 | 功能 |
|---|---|
| `list_tags` | 您的图书馆中的所有标签；传递 `collection_id` 以限定范围 |
| `rename_tag` | 在其出现的所有位置重命名标签 |
| `delete_tags` | 从所有书签中删除一个或多个标签 |
---
## 清理工作流
Rainkeeper 适用于 inbox-zero 清理：处理未分类的内容，为每个项目添加标签和归档，不留任何内容。
```
"列出我的未分类集合中的所有内容，并为每个项目建议一个集合。"
"将所有标记为 #read-later 的书签移动到我的阅读集合中。"
"搜索过去 30 天内标记为 #ai 的所有内容，并列出标题和网址。"
"在我的整个图书馆中将标签 'ai-tools' 重命名为 'ai'。"
"根据标题将最近的 20 个书签归档到正确的集合中。"
"删除未分类中所有超过 6 个月的内容。"
```
---
## 架构
```
rainkeeper/
├── src/
│ └── rainkeeper/
│ ├── server.py FastMCP 应用 · 注册所有工具
│ ├── client.py RaindropClient · 所有 HTTP 操作
│ ├── config.py RAINDROP_ACCESS_TOKEN · BASE_URL · headers
│ └── tools/
│ ├── collections.py 5 个工具 — list · get · create · update · delete
│ ├── raindrops.py 6 个工具 — list · get · create · update · move · delete
│ ├── bulk.py 4 个工具 — move · tag · star · delete（批量）
│ ├── search.py 1 个工具 — 全文 + Raindrop 语法
│ └── tags.py 3 个工具 — list · rename · delete
├── .env.example 令牌模板 — 复制到 .env，永远不要提交 .env
├── pyproject.toml 可安装包 · rainkeeper CLI 入口点
└── README.md
```
**设计规则：** `RaindropClient` 拥有所有 HTTP 操作。工具是薄的包装 — 没有 `httpx` 在工具文件中。API 映射（包括集合移动修复）在一个地方强制执行，并且可以独立于 MCP 层进行测试。
---
## 已知限制
以下 Raindrop.io API 功能尚未公开。如果这些功能对您的工作流程很重要，请提出 [功能请求](https://github.com/simonives/rainkeeper/issues/new?template=feature_request.md)，或在 [讨论中提出想法](https://github.com/simonives/rainkeeper/discussions)。
- **高亮** — 在书签中创建和读取高亮
- **用户配置文件** — `GET /user`（便于验证身份验证是否正常）
- **导入/导出** — 批量 HTML 书签导入，导出到文件
- **共享** — 共享集合管理
- **OAuth 2.0** — 多用户身份验证；目前仅限个人测试令牌
---
## 贡献
Rainkeeper 由 [@simonives](https://github.com/simonives) 维护。参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解如何报告错误、提出功能请求和分叉项目。
---
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
---
<div align="center">
<sub>使用 <a href="https://github.com/jlowin/fastmcp">FastMCP</a> · <a href="https://developer.raindrop.io">Raindrop.io REST API v1</a> 构建</sub>
</div>
