Raindrop.io MCP服务器
    
基于FastMCP的模型上下文协议服务器，用于向 AI助手。服务器专注于丰富的书签、收藏、标签、突出显示， 过滤器、批处理操作和帐户操作，同时遵循最新 Raindrop REST文档。
关键能力
- 现代雨滴API覆盖范围 –为收藏、书签、，
标签、突出显示/注释、帐户配置文件和跨收藏搜索。
- 批量操作 –用于移动、删除、更新、标记和
一次取消标记多个书签。
- 高级过滤 –用于将复杂过滤器应用于搜索和
整理书签。
- 导入/导出 –从外部源导入书签的功能
并以各种格式导出。
- FastMCP工具 –使用丰富元数据注册的工具，以便助手可以
浏览、过滤、创建、更新和删除自然流中的雨滴实体。
- 类型化配置 –
RaindropSettings验证环境变量
并公开stdio或流式HTTP传输的切换。
- 可重用HTTP客户端 –支持重试，对速率限制友好
RaindropClient
带有显式错误映射和分页助手。
- 经过测试的实施 –涵盖客户端、工具和
入口设有覆盖护栏（≥80%）。
架构概述
入门指南
先决条件
安装
# clone and install dependencies
git clone https://github.com/lesleslie/raindropio-mcp.git
cd raindropio-mcp
uv sync配置
设置 RAINDROP_TOKEN 启动服务器之前的环境变量。你 可以导出值或将其放入 .env 项目根目录旁边的文件。
export RAINDROP_TOKEN="your-raindrop-token"可选环境变量（均以前缀 RAINDROP_):
| 变量 | 默认值 | 描述 |
|---|---|---|
RAINDROP_USER_AGENT | raindropio-mcp/0.1.0 | HTTP用户代理标头 |
RAINDROP_REQUEST_TIMEOUT | 30.0 | HTTP请求超时前的秒数 |
RAINDROP_MAX_CONNECTIONS | 10 | 最大并发HTTP连接数 |
RAINDROP_ENABLE_HTTP_TRANSPORT | false | 启用流式HTTP传输 |
RAINDROP_HTTP_HOST | 127.0.0.1 | 启用HTTP绑定主机时 |
RAINDROP_HTTP_PORT | 3034 | 启用HTTP端口时 |
RAINDROP_HTTP_PATH | /mcp | MCP端点的HTTP路径 |
运行服务器
# stdio (default)
uv run python -m raindropio_mcp
# or via the console script
uv run raindropio-mcp
# HTTP mode
uv run python -m raindropio_mcp --http --http-port 3034example.mcp.json 和 example.mcp.dev.json 演示如何连接服务器 支持MCP的客户端，如Claude Desktop或PowerShell集成。
快速启动流程图
可用工具
所有工具均已声明 raindropio_mcp/tools 并由自动注册 register_all_tools.
| 类别 | 工具 | 描述 |
|---|---|---|
| 收藏 | list_collections | 获取令牌可见的每个集合 |
get_collection | 加载特定集合的元数据 | |
create_collection | 创建新的收藏集/文件夹 | |
update_collection | 更新标题、描述或外观 | |
delete_collection | 删除收藏（项目移动到收件箱） | |
| 书签 | list_bookmarks | 使用分页/搜索功能列出收藏中的书签 |
search_bookmarks | 在所有收藏中进行全文搜索 | |
get_bookmark | 按id检索书签 | |
create_bookmark | 向收藏添加书签 | |
update_bookmark | 编辑书签元数据或在集合之间移动 | |
delete_bookmark | 删除书签 | |
| 亮点 | list_highlights | 列出特定书签的所有亮点 |
get_highlight | 按ID获取单个突出显示 | |
create_highlight | 为书签创建新的突出显示 | |
update_highlight | 更新现有突出显示 | |
delete_highlight | 按ID删除突出显示 | |
| 批次 | batch_move_bookmarks | 将多个书签移动到不同的收藏中 |
batch_delete_bookmarks | 删除多个书签 | |
batch_update_bookmarks | 用相同的更改更新多个书签 | |
batch_tag_bookmarks | 为多个书签添加标签 | |
batch_untag_bookmarks | 从多个书签中删除标签 | |
| 过滤器 | apply_filters | 应用各种过滤器在所有收藏中搜索和组织书签 |
get_filtered_bookmarks_by_collection | 对特定收藏中的书签应用过滤器 | |
| 进口/出口 | import_bookmarks | 将书签从外部源导入Raindrop.io |
export_bookmarks | 以指定格式从Raindrop.io导出书签 | |
| 标签 | list_tags | 获取标签使用计数 |
rename_tag | 全局重命名标签 | |
delete_tag | 删除所有书签中的标签 | |
账户 get_account_profile | 返回经过身份验证的帐户配置文件 | |
| 系统 | ping | 轻量级心跳，包括时间戳 |
每个工具返回与官方API非常匹配的JSON系列有效载荷 这样下游代理就可以在不进行额外解析的情况下使用数据。
工具类别概述
可观察性和关机
日志默认为结构化JSON。集 RAINDROP_OBSERVABILITY_STRUCTURED_LOGGING=false （或通过以下方式覆盖 .env)切换到经典文本格式。
FastMCP应用程序注册了一个关闭钩子，可以优雅地关闭共享 RaindropClient，确保在服务器启动时释放HTTP连接池 终止。
开发工作流程
# lint + type-check + tests + security
uv run crackerjack
# individual tasks
uv run ruff check --fix
uv run mypy .
uv run pytest --cov=. --cov-report=term-missing测试夹具带电 tests/ 并自动注射 RAINDROP_TOKEN 所以单位 执行永远不会到达实时API。
路线图
- 为高容量助手工作流添加可选的缓存中间件
- 在Raindrop暴露这些端点时实现共享功能
- 通过附加选项增强过滤器功能
欢迎通过问题或拉取请求提供贡献和功能建议。