MCP 服务器

douban-mcp

MCP server and CLI for accessing Douban movie and book data, including search, details, reviews, charts, and user collections. Supports read-only and write operations (mark movies/books) when authenticated.

README

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	标记/取消标记图书

📚 文档

⚙️ 环境变量

变量	默认	说明
`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