douban-mcp
This server provides read-only Douban data lookups for movies, books, and user profiles/collections.
Search movies and books by keyword (with result count control)
Fetch movie and book details (director/cast, author/publisher/ISBN, ratings, summaries) by subject id
List short reviews for a movie or book
Browse movie charts (Top250, weekly, new) and book charts (fiction, non-fiction, new)
View a user's 想看/在看/看过 collections (movie or book) with pagination
View a user's doulist and profile info
Use anonymously for search/chart aggregation; detail pages and user lookups without
uidtypically need a Douban cookie configuredNo write operations are exposed in this schema—all listed tools are read-only
Provides tools for searching and retrieving movie and book information, user collections, and ratings on Douban, as well as marking and rating movies and books.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@douban-mcp show me the top 250 movies"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
douban-mcp 🎬 📕
面向 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:短评写操作
Related MCP server: douban-mcp
🚀 快速开始
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 签名缺失),代码已移除。仍设置该值会立刻报AUTH_FAILED并提示改回html。
🛠️ 工具清单
只读(默认全部可用)
工具 | 鉴权 | 说明 |
| 无 | 关键词搜索电影 |
| 无 | 电影详情 |
| 无 | 短评列表 |
| 无 | 榜单 (top250 / weekly / new) |
| 无 | 关键词搜索图书 |
| 无 | 图书详情 |
| 无 | 短评列表 |
| 无 | 榜单 (fiction / non_fiction / new) |
| uid 缺省时需 cookie | 想看/在看/看过列表 |
| uid 缺省时需 cookie | 豆列 |
| uid 缺省时需 cookie | 用户信息 |
鉴权 / 写
工具 | 鉴权 | 说明 |
| cookie | cookie 是否有效 |
| cookie + DOUBAN_ENABLE_WRITE | 标记/取消标记电影 |
| cookie + DOUBAN_ENABLE_WRITE | 标记/取消标记图书 |
📚 文档
⚙️ 环境变量
变量 | 默认 | 说明 |
| — | 登录态 cookie |
|
| 启用写操作 |
|
| 仅支持 |
|
| debug/info/warn/error |
|
| 关闭缓存(测试用) |
| 内置 Chrome UA | 覆盖默认 UA |
|
| HTTP 模式监听地址( |
🔧 HTTP 模式(Streamable HTTP)
npx -y douban-mcp-cli serve --transport http --port 3000
# 然后在 MCP 客户端连接 http://127.0.0.1:3000/mcp同一个进程同时提供:
端点 | 协议 | 状态 |
| Streamable HTTP(2025-03-26+), | 推荐 |
| HTTP+SSE(2024-11-05) | 已废弃,仅为旧客户端保留 |
--transport sse 仍可用,但只是 http 的别名并打印废弃警告;请把客户端迁到 /mcp。每个会话独立一个 MCP server 实例,多个客户端可同时连接。
默认只监听 127.0.0.1,并校验 Host / Origin 防 DNS rebinding。端点本身没有鉴权,而且会代理你的豆瓣登录态,所以要暴露给其他机器时必须显式指定,并自行加防火墙或反向代理:
npx -y douban-mcp-cli serve --transport http --port 3000 --host 0.0.0.0🧰 调试
# 用 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🛡️ 免责声明
本项目仅供学习和个人使用,禁止用于商业目的或大规模数据爬取。使用本项目造成的任何账号风险(限流、封禁等)由使用者自行承担。本项目无任何官方背景。
Available Tools
11 toolsget_bookARead-only
获取图书详情(作者、出版、ISBN、简介等)。id 是豆瓣图书 subject id(数字)。
Inputs: id (required).
get_book_chartCRead-only
获取图书榜单。kind: fiction (小说)、non_fiction (随笔)、new (新书速递)。
Inputs: kind (required), count.
get_book_reviewsCRead-only
获取图书的短评列表。
Inputs: id (required), count.
get_movieARead-only
获取一部电影的详细信息(导演、演员、评分、简介等)。id 是豆瓣电影 subject id(数字)。
Inputs: id (required).
get_movie_chartBRead-only
获取电影榜单。kind: top250 (Top250)、weekly (一周口碑榜)、new (近期上映)。
Inputs: kind (required), count, start.
get_movie_reviewsBRead-only
获取一部电影的短评列表(不含长评)。
Inputs: id (required), count.
get_user_collectionsBRead-only
获取某用户的"想看/在看/看过"列表。无 cookie 时必须传 uid。
Inputs: uid (required), status (required), category (required), count, +1 more.
get_user_doulistARead-only
获取某用户的豆列清单。无 cookie 时必须传 uid。
Inputs: uid (required).
get_user_profileBRead-only
获取某用户的基本信息。无 cookie 时必须传 uid。
Inputs: uid (required).
search_bookBRead-only
按关键词搜索豆瓣图书。
Inputs: q (required), count.
search_movieARead-only
按关键词搜索豆瓣电影。返回标题/年份/评分/链接的 markdown 列表。
Inputs: q (required), count.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
Unofficial Movies MCP — wraps iTunes Search API (movies, free, no auth) and TVmaze API (TV shows…
Movie and series ranking as MCP tools: top titles, search, lookup by IMDb id. Free, no key.
Books MCP — wraps Open Library API (free, no auth)
Chinese company registry, litigation, IP and credit data for AI agents. Read-only remote MCP server.
15
Related MCP Servers
- FlicenseAqualityDmaintenanceAn MCP server that wraps The Movie Database (TMDB) API, enabling search for movies and TV shows, retrieval of movie details, recommendations, similar movies, trending content, streaming providers, and movie discovery.8-
- AlicenseCqualityDmaintenanceMCP server for querying Douban books, movies, TV shows, and group topics, with tools for searching, retrieving details, and listing reviews.10MIT
- AlicenseAqualityBmaintenanceMCP server for The Movie Database (TMDB): search and look up movies, TV shows and people, and read IMDb/Rotten Tomatoes/Metacritic ratings (via OMDb) in the same call.23366 npm6MIT
- AlicenseNot gradedqualityBmaintenanceOfficial MCP server for the DDYS (低端影视) API, enabling search, details, resources, collections, comments, and media export (STRM, M3U) via natural language.17 npmMIT