Cove Douban MCP

一个独立、可开源、默认只读的豆瓣 MCP 服务。它把本地 Chrome 中已经可见的豆瓣信息，通过标准 Model Context Protocol 提供给 Claude Code、Codex、桌面客户端、编辑器插件，以及开发者自己的前端或后端。

项目支持 macOS 与 Windows，提供 stdio 和仅限本机回环地址的 Streamable HTTP。它不依赖 Cove 主程序，也不会读取或修改任何 Cove 数据。

本项目与豆瓣无隶属、合作或官方授权关系。请遵守豆瓣条款、当地法律和账号 权限边界，仅访问你本来就有权在浏览器中查看的内容。

核心边界

• 豆瓣侧永久只读：不标记、不评分、不发影评、不改豆列、不改账号。

• 不索取、不导出、不持久化 Cookie；不复制 Chrome profile。

• 默认只写自己的缓存目录。

• Markdown 导出功能存在，但默认关闭。

• confirm_each 模式下，模型只能发起一次性提案，不能批准自己的提案。

• 本地 HTTP 只能绑定 127.0.0.1、localhost 或 ::1，并强制 Bearer 鉴权和浏览器 Origin 检查。

• 安装前检测同名 OpenCLI adapter；默认绝不覆盖。

• 卸载时仅删除哈希仍与安装包一致的 adapter，用户后来改过的文件会保留。

Related MCP server: douban-mcp

能做什么

当前版本提供以下只读能力：

douban_chart 支持电影一周口碑榜、北美票房榜、新片榜、Top 250、热门图书榜 和热门音乐榜。它只接受固定榜单键与数量，不接受任意网址或浏览器脚本；原有 11 个 v0.1.x 工具合同保持不变。

架构

flowchart LR
    Client["任意标准 MCP 客户端"] --> Transport["stdio / 本机 Streamable HTTP"]
    Transport --> Tools["12 个薄 MCP 工具"]
    Tools --> Services["查询、筛选、同步、导出服务"]
    Services --> Cache["四层私有本地缓存"]
    Services --> Gateway["命令白名单 + 无 shell 子进程"]
    Gateway --> OpenCLI["8 个只读 OpenCLI adapter"]
    OpenCLI --> Chrome["用户当前 Chrome 会话"]
    Chrome --> Douban["浏览器中本来可见的豆瓣页面"]

领域层负责标准化、筛选、分页、非缩水合并和不透明结果引用；MCP 层不直接 解析网页。两种传输共用同一个服务容器，因此结果合同一致。

系统要求

• macOS 13 或更新版本，或受支持的 Windows 10/11；

• Python 3.11、3.12 或 3.13；

• uv（推荐）或能安装 Python wheel 的工具；

• Node.js 22；

• OpenCLI 1.8.x；

• Chrome，以及可用的 OpenCLI Browser Bridge；

• 已在该 Chrome 会话中正常登录豆瓣。

本项目不会自动升级全局 OpenCLI。doctor 会报告版本不匹配并给出处理建议。

安装

方法一：从 GitHub Release 安装（推荐）

打开 Releases， 下载 cove_douban_mcp-0.2.0-py3-none-any.whl，然后在下载目录运行：

uv tool install ./cove_douban_mcp-0.2.0-py3-none-any.whl

没有使用 uv 时，也可以安装到当前 Python 环境：

python -m pip install ./cove_douban_mcp-0.2.0-py3-none-any.whl

Windows 如果使用 Python Launcher，可以运行：

py -m pip install .\cove_douban_mcp-0.2.0-py3-none-any.whl

从 v0.1.x 升级时，安装器会刻意拒绝覆盖已有 adapter。请先使用仍在 运行的旧版卸载未修改的托管文件，再替换工具并安装新版只读 adapter：

cove-douban-mcp uninstall
uv tool install --force ./cove_douban_mcp-0.2.0-py3-none-any.whl
cove-douban-mcp setup --yes
cove-douban-mcp doctor --json

uninstall 只删除内容仍与当时安装包一致的 adapter；用户修改过的 adapter 会保留。如果 setup 报告冲突，请先备份并显式移除它报告的文件， 然后重试。升级过程不会修改 MCP 客户端配置或豆瓣数据。

方法二：从源码安装

git clone <repository-url>
cd cove-douban-mcp
uv tool install .

先看安装计划，不改任何文件：

cove-douban-mcp setup --dry-run

确认后安装默认配置和八个只读 adapter：

cove-douban-mcp setup --yes

setup 不会修改任何 MCP 客户端配置。它会输出一份通用配置，用户自行决定 放进哪个客户端。

连接任意 MCP 客户端

stdio（推荐）

完整示例见 examples/generic-stdio.json：

{
  "mcpServers": {
    "douban": {
      "command": "cove-douban-mcp",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

这是一份标准 MCP stdio 配置，不绑定某个厂商。若客户端使用不同字段名，请 把同一条 command/args 映射进去即可。

本机 Streamable HTTP

启动：

cove-douban-mcp serve --transport streamable-http

默认端点是 http://127.0.0.1:8765/mcp。首次启动会在应用数据目录生成 至少 256 位的本地 token；服务不会把 token 打到日志或 MCP 结果中。 macOS 使用仅限文件所有者的权限，Windows 使用 icacls 移除继承权限并 只授权当前用户；如果无法建立这层保护，本地 HTTP 会拒绝启动并清理新令牌。

完整结构见 examples/generic-streamable-http.json。 浏览器前端不应把 token 写进源码；请由同机后端代持，或使用 stdio。

随时生成通用配置：

cove-douban-mcp print-config --transport stdio
cove-douban-mcp print-config --transport streamable-http

首次使用

1. 在 Chrome 中正常打开豆瓣并完成登录。

2. 确认 OpenCLI Browser Bridge 可用。

3. 运行 cove-douban-mcp doctor --json。

4. 在 MCP 客户端调用 douban_status。

5. 用 douban_search、douban_chart 或 douban_movie_marks 做第一条只读查询。

doctor 不执行私有账号数据抓取，只检查本地文件、插件和 OpenCLI 可执行文件。

缓存与同步

应用使用四层缓存：

• 六小时、有上限的普通查询缓存；

• “看过 / 想看 / 在看”的非缩水持久基线；

• 同步状态；

• 24 小时、按客户端隔离的不透明完整结果引用。

筛选发生在分页之前。普通增量更新只会补充或丰富旧条目，不会因为一次网页 只返回部分内容而把历史基线截短。

默认同步状态为启用，每日目标时间为本地 05:10，默认同步 wish、 collect 和豆列。手动调用 douban_sync 始终只写内部缓存，不写豆瓣。 观影标记同步使用有界的轻量列表分块，不会逐条打开影片详情页；已有的类型、 国家、导演和演员等丰富字段会由非缩水合并保留。多个本地 MCP 进程会串行使用 同一个 Browser Bridge，避免互相抢占浏览器页面。

可选 Markdown 导出

默认：

[export]
enabled = false
policy = "off"

允许每次人工确认：

cove-douban-mcp permissions export \
  --policy confirm_each \
  --root "/path/selected/by/user"

允许在一个固定根目录内直接写：

cove-douban-mcp permissions export \
  --policy allow_in_root \
  --root "/path/selected/by/user"

Windows PowerShell 同样使用用户自己选择的绝对路径：

cove-douban-mcp permissions export `
  --policy confirm_each `
  --root "D:\Documents\DoubanExports"

人工提案命令：

cove-douban-mcp export list
cove-douban-mcp export show <proposal-id>
cove-douban-mcp export approve <proposal-id>
cove-douban-mcp export reject <proposal-id>

导出只接受 .md 和 .markdown，会拒绝 ..、根目录外绝对路径、符号链接 逃逸和 Windows junction/reparse-point 逃逸。replace 只替换本项目标记的 生成区块，并先创建可恢复备份。

数据位置

macOS：

~/Library/Application Support/cove-douban-mcp/

Windows：

%LOCALAPPDATA%\cove-douban-mcp\

其中只有配置、缓存、同步状态、提案、脱敏诊断信息和本地 HTTP 凭据；没有 Cookie、密码、Chrome profile 或 MCP 对话历史。

卸载

移除 OpenCLI 集成、保留缓存和配置：

cove-douban-mcp uninstall --yes

连应用数据一起清除需要第二次明确确认：

cove-douban-mcp uninstall --yes --purge-data --confirm-purge

无论哪种方式，都不会删除已经导出的 Markdown。

开发

uv sync --all-groups
uv run ruff check .
uv run mypy src
uv run pytest -q
npm --prefix opencli-plugin ci
npm --prefix opencli-plugin test

默认测试完全使用合成数据，不连接豆瓣。参见 CONTRIBUTING.md。

安全、隐私与排障

• 安全设计

• 隐私说明

• 故障排查

• 漏洞报告政策

许可证

Apache License 2.0。第三方归属见 NOTICE。