douban-mcp
# douban-mcp 🎬 📕
[](https://www.npmjs.com/package/douban-mcp-cli)
[](https://github.com/jackjin1997/douban-mcp/actions)
[](LICENSE)
**面向 agent 的豆瓣 MCP 服务 + CLI**。同一个包既能做 Claude Desktop 的 MCP server(stdio / Streamable HTTP),又能给 Claude Code/OpenClaw 等 agent 直接当 CLI 用。
> npm 包名为 `douban-mcp-cli`(裸名 `douban-mcp` 在 npm 已被他人占用);GitHub 仓库 / 产品名仍为 `douban-mcp`。
## ✨ 特性
- ✅ 11 个匿名只读工具(电影 / 图书 / 用户态 全覆盖)+ 1 个登录态 cookie 自检工具
- ✅ 4 个写工具(标记想看/在看/看过 + 打分 + 评论 + 标签),双模式 opt-in
- ✅ 唯一数据源为 HTML(axios + cheerio);原 Frodo App API 通道因服务端签名要求已移除
- ✅ MCP server (stdio + Streamable HTTP,兼容旧 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`:
```json
{
"mcpServers": {
"douban": {
"command": "npx",
"args": ["-y", "douban-mcp-cli", "serve"],
"env": { "DOUBAN_COOKIE": "你的cookie(可选)" }
}
}
}
```
### CLI(任何 agent / 命令行)
```bash
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
```
启用写操作:
```bash
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 签名缺失`),代码已移除。仍设置该值会立刻报 `AUTH_FAILED` 并提示改回 `html`。
## 🛠️ 工具清单
### 只读(默认全部可用)
| 工具 | 鉴权 | 说明 |
|---|---|---|
| `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 获取](docs/cookie-guide.md)
- [常见问题](docs/faq.md)
- [架构](docs/architecture.md)
- [设计 spec](docs/superpowers/specs/2026-05-07-douban-mcp-design.md)
- [实施计划](docs/superpowers/plans/2026-05-07-douban-mcp-v1.md)
- [贡献指南](CONTRIBUTING.md)
- [变更日志](CHANGELOG.md)
- [已知问题](docs/jack_todo.md)
## ⚙️ 环境变量
| 变量 | 默认 | 说明 |
|---|---|---|
| `DOUBAN_COOKIE` | — | 登录态 cookie |
| `DOUBAN_ENABLE_WRITE` | `false` | 启用写操作 |
| `DOUBAN_DATA_SOURCE` | `html` | 仅支持 `html`;`frodo` 已移除,设置后直接报错 |
| `DOUBAN_LOG_LEVEL` | `info` | debug/info/warn/error |
| `DOUBAN_DISABLE_CACHE` | `false` | 关闭缓存(测试用) |
| `DOUBAN_USER_AGENT` | 内置 Chrome UA | 覆盖默认 UA |
| `DOUBAN_HOST` | `127.0.0.1` | HTTP 模式监听地址(`--host` 优先) |
## 🔧 HTTP 模式(Streamable HTTP)
```bash
npx -y douban-mcp-cli serve --transport http --port 3000
# 然后在 MCP 客户端连接 http://127.0.0.1:3000/mcp
```
同一个进程同时提供:
| 端点 | 协议 | 状态 |
|---|---|---|
| `/mcp` | Streamable HTTP(2025-03-26+),`Mcp-Session-Id` 会话 | 推荐 |
| `/sse` + `/messages` | HTTP+SSE(2024-11-05) | 已废弃,仅为旧客户端保留 |
`--transport sse` 仍可用,但只是 `http` 的别名并打印废弃警告;请把客户端迁到 `/mcp`。每个会话独立一个 MCP server 实例,多个客户端可同时连接。
默认只监听 `127.0.0.1`,并校验 `Host` / `Origin` 防 DNS rebinding。端点本身没有鉴权,而且会代理你的豆瓣登录态,所以要暴露给其他机器时必须显式指定,并自行加防火墙或反向代理:
```bash
npx -y douban-mcp-cli serve --transport http --port 3000 --host 0.0.0.0
```
## 🧰 调试
```bash
# 用 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
```
## 🛡️ 免责声明
本项目仅供学习和个人使用,禁止用于商业目的或大规模数据爬取。使用本项目造成的任何账号风险(限流、封禁等)由使用者自行承担。本项目无任何官方背景。
TDQS
Scored across 11 tools
Tools split cleanly along two axes: resource (movie/book/user) and action (search/get/reviews/chart/collections/doulist/profile). The movie and book families are perfectly parallel, so an agent can pick the right tool from the name plus the kind parameter alone. No two tools overlap in scope.
Every tool follows a strict snake_case verb_noun pattern (search_movie, get_movie_reviews, get_user_doulist). Resource-first grouping (movie_*/book_*/user_*) makes the families obvious. No mixed conventions or vague verbs.
11 tools is squarely in the sweet spot, and each one earns its place: four per media type plus three user tools. The symmetric design means no filler tools and no obvious redundancy.
Read coverage is solid for movies, books, and user lists, including charts and short reviews. Gaps remain: no write operations (marking watched/want-to-watch), no long-review retrieval, no user search, and no music/media coverage despite the broad 'douban' name.