douban-mcp 🎬 📕

面向 agent 的豆瓣 MCP 服务 + CLI。同一个包既能做 Claude Desktop 的 MCP server（stdio/SSE），又能给 Claude Code/OpenClaw 等 agent 直接当 CLI 用。

npm 包名为 douban-mcp-cli（裸名 douban-mcp 在 npm 已被他人占用）；GitHub 仓库 / 产品名仍为 douban-mcp。

✨ 特性

• ✅ 12 个只读工具（电影 / 图书 / 用户态 全覆盖）
• ✅ 4 个写工具（标记想看/在看/看过 + 打分 + 评论 + 标签），双模式 opt-in
• ✅ 双数据源（HTML 默认 / Frodo API 可选），随时切换
• ✅ MCP server (stdio + SSE) + agent native CLI（--json 模式）
• ✅ Claude Code Skill 包随仓库交付
• ✅ 内置缓存 + 限速 + 风控退避
• ⏳ v1.1：覆盖率 90%+；user search、doulist items
• ⏳ v1.2：短评写操作

🚀 快速开始

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "douban": {
      "command": "npx",
      "args": ["-y", "douban-mcp-cli", "serve"],
      "env": { "DOUBAN_COOKIE": "你的cookie（可选）" }
    }
  }
}

CLI（任何 agent / 命令行）

npx -y douban-mcp-cli search-movie --q "盗梦空间" --count 3
npx -y douban-mcp-cli get-movie --id 3541415
npx -y douban-mcp-cli --json movie-chart --kind top250 --count 5 | jq

启用写操作：

export DOUBAN_COOKIE="bid=...; dbcl2=\"...\"; ck=...; ll=\"108288\""
export DOUBAN_ENABLE_WRITE=true
npx -y douban-mcp-cli mark-movie --id 3541415 --status collect --rating 5

⚠️ 写操作有触发风控/封号风险。建议先用小号验证；本项目对账号安全不承担责任。

⚠️ 关于详情页必须配 cookie

v1.0 实测：search- 和 movie-chart top250 等聚合页匿名可用*；但 get-movie / get-book / get-*-reviews 等详情页会被豆瓣风控重定向到 sec.douban.com，必须配置 DOUBAN_COOKIE 才能稳定访问。

匿名模式下详情页会得到一条清晰错误：

⚠️ 豆瓣对该页面触发了风控（详情页常见）。请配置 DOUBAN_COOKIE 后重试。

注：原先设计的 DOUBAN_DATA_SOURCE=frodo 备用通道（豆瓣 App API）目前已被服务端加签名要求拦截（invalid_request_997 签名缺失），v1.0 不可用。详见 docs/jack_todo.md。v1.x 计划做 cookie warm-up + 探索签名逆向。

🛠️ 工具清单

只读（默认全部可用）

工具	鉴权	说明
search_movie	无	关键词搜索电影
get_movie	无	电影详情
get_movie_reviews	无	短评列表
get_movie_chart	无	榜单 (top250 / weekly / new)
search_book	无	关键词搜索图书
get_book	无	图书详情
get_book_reviews	无	短评列表
get_book_chart	无	榜单 (fiction / non_fiction / new)
get_user_collections	uid 缺省时需 cookie	想看/在看/看过列表
get_user_doulist	uid 缺省时需 cookie	豆列
get_user_profile	uid 缺省时需 cookie	用户信息

鉴权 / 写

工具	鉴权	说明
check_cookie	cookie	cookie 是否有效
mark_movie / unmark_movie	cookie + DOUBAN_ENABLE_WRITE	标记/取消标记电影
mark_book / unmark_book	cookie + DOUBAN_ENABLE_WRITE	标记/取消标记图书

📚 文档

• Cookie 获取
• 常见问题
• 架构
• 设计 spec
• 实施计划
• 贡献指南
• 变更日志
• 已知问题

⚙️ 环境变量

变量	默认	说明
DOUBAN_COOKIE	—	登录态 cookie
DOUBAN_ENABLE_WRITE	false	启用写操作
DOUBAN_DATA_SOURCE	html	html / frodo
DOUBAN_FRODO_APIKEY	内置默认	覆盖 frodo apikey
DOUBAN_LOG_LEVEL	info	debug/info/warn/error
DOUBAN_DISABLE_CACHE	false	关闭缓存（测试用）
DOUBAN_USER_AGENT	内置 Chrome UA	覆盖默认 UA

🔧 SSE 模式

npx -y douban-mcp-cli serve --transport sse --port 3000
# 然后在 MCP 客户端连接 http://localhost:3000/sse

🧰 调试

# 用 mcp-inspector 一键调试
npx @modelcontextprotocol/inspector npx -y douban-mcp-cli serve

# 直接命令行调用任何工具（agent 也用这种方式）
npx -y douban-mcp-cli list-tools
npx -y douban-mcp-cli describe search-movie
npx -y douban-mcp-cli doctor

🛡️ 免责声明

本项目仅供学习和个人使用，禁止用于商业目的或大规模数据爬取。使用本项目造成的任何账号风险（限流、封禁等）由使用者自行承担。本项目无任何官方背景。