TMDB MCP Server

TMDB MCP 服务

一个用于 The Movie Database（TMDB）API 的 MCP 服务。它提供电影和电视节目搜索、流媒体可用性、演职人员详情以及推荐，适用于 Codex 和 Claude Desktop 等助手。

如需了解可复用 MCP 服务与更高层级功能工作流之间的架构划分，请参阅 USERGUIDE.md。

工具

电影发现

• get_weekend_watchlist — 根据心情、国家、语言、片长、评分和服务，生成排名后的周末观影候选清单
• plan_watch_party — 电影之夜小组计划，包含首选影片、备选影片、惊喜影片、适合聚会的理由、服务可用性和排除影片筛选
• build_franchise_watch_order — 系列／宇宙观影指南，包含上映顺序、建议顺序、总片长和考虑服务可用性的备注
• build_collection_gap_plan — 系列补完计划，包含已看／未看条目、剩余片长、服务可用性和补完路径
• recommend_from_taste_profile — 根据喜欢／不喜欢的影片进行推荐，包含考虑服务可用性的评分、匹配理由和注意事项
• build_release_calendar_watchlist — 按上映时间段整理的观影清单，包含即将上映的电影、可在服务上观看的影片、面向广泛观众的基准选择和稍后观看评分
• search_movies — 按标题／关键词搜索 → 标题、ID、评分、简介
• get_trending — 热门电影前 10 名（timeWindow："day" | "week"）
• get_weekly_trending_by_language — 按原始语言分组的每周热门电影，分为英语、印地语和泰卢固语
• search_by_genre — 按类型名称搜索电影，可选年份筛选
• advanced_search — 按类型、年份、最低评分、排序方式和语言筛选
• search_by_keyword — 按主题／关键词查找电影（例如“僵尸”“劫案”）

电影详情

• get_movie_details — 完整详情：演职人员、片长、类型、评论（按 movieId）
• compare_movies — 对 2-5 个电影 ID 进行并列比较，包含评分、片长、演员、导演、服务和适配度最佳的备注
• get_recommendations — 根据电影 ID 推荐前 5 部影片
• get_similar_movies — 通过 TMDB 的相似度算法查找相似电影
• get_watch_providers — 按国家查询流媒体／租赁／购买可用性（默认值：IN）
• find_where_to_watch — 搜索 1-5 部电影，并返回流媒体／租赁／购买可用性及首选服务匹配项

电视节目

• search_tv_shows — 按标题搜索电视连续剧
• get_trending_tv — 热门电视节目前 10 名（timeWindow："day" | "week"）

人物

• search_person — 按姓名查找演员、导演和剧组人员 → ID + 知名作品
• get_person_details — 按 personId 获取完整简介和影视作品目录（电影 + 电视）
• build_person_watch_path — 演员／导演观影路径，包含评分最高、当前可观看、近期作品和入门推荐

资源

• tmdb:///movie/<id> — JSON 格式的完整电影详情（标题、演员、导演、评论、海报 URL）

快速开始

1. 在 themoviedb.org → Account Settings → API 获取 TMDB API 密钥

2. 克隆、安装并构建：

   git clone https://github.com/Laksh-star/mcp-server-tmdb.git
   cd mcp-server-tmdb
   npm install
   

3. 创建本地环境文件并添加 TMDB 密钥：

   cp .env.example .env
   

4. 安装本地 Codex 和 Claude Desktop 集成：

   npm run install:local
   

5. 如果 Codex 或 Claude Desktop 已打开，请重启。

6. 使用类似以下提示词进行验证：

   What movies are trending this week?
   

在 Codex 中，新会话应在插件列表中显示 TMDB，并提供 mcp__tmdb__ 命名空间。

工具表面冒烟测试

添加或合并工具后，请使用此冒烟测试。它会验证预期的 MCP 工具契约，并调用主要工作流工具：compare_movies、find_where_to_watch、get_weekend_watchlist、plan_watch_party、build_franchise_watch_order、build_collection_gap_plan、recommend_from_taste_profile 和 build_person_watch_path。

本地 stdio MCP：

npm run build
set -a && source ./.env && set +a && npm run smoke:tools

由 Cloudflare 托管的 MCP：

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/tool-surface-smoke.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp

脚本会将精简的验证产物写入：

examples/tool-surface-smoke.md

为避免工具臃肿，优先添加能将多个 TMDB 调用整合为实用用户决策的工作流工具。仅在原始端点式工具可广泛复用时才保留它们。

每周热门语言演示

此仓库包含一个小型、可分享的演示，它会调用 MCP 工具 get_weekly_trending_by_language。该工具会获取 TMDB 每周热门电影的实时数据，并按 TMDB 的 original_language 对当前第一页的电影进行分组。

对本地 stdio MCP 服务运行：

npm run build
set -a && source ./.env && set +a && npm run demo:weekly-trending

部署此版本的 Worker 后，对远程 MCP 端点运行相同的演示：

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/weekly-trending-languages.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp

如果部署有意不启用身份验证，以便个人测试，请省略 TMDB_MCP_ACCESS_TOKEN。

每周流媒体雷达

此仓库还包含一个以脚本为主的每周雷达。它会串联现有 MCP 工具，生成 Markdown 产物，其中包含电影趋势、电视趋势、语言热度、可立即采取行动的精选、适合家庭观看的精选，以及口味档案探测。

本地 stdio MCP：

npm run build
set -a && source ./.env && set +a && npm run demo:weekly-radar -- --country US

由 Cloudflare 托管的 MCP：

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/weekly-streaming-radar.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --country US

脚本会写入：

examples/weekly-streaming-radar.md

上映日历片单

上映日历可通过 MCP 工具 build_release_calendar_watchlist 使用。演示脚本会调用该工具，并生成 Markdown 产物，用于扫描上映窗口、整理稍后观看的候选影片、筛选可通过服务商观看的影片，以及确定适合广泛受众的基准选择。

本地 stdio MCP：

npm run build
set -a && source ./.env && set +a && npm run demo:release-calendar -- --country US --days 90

由 Cloudflare 托管的 MCP：

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/release-calendar-watchlist.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --country US --days 90

脚本会写入：

examples/release-calendar-watchlist.md

服务商变更监控器

由于需要持久化状态，服务商监控器以脚本为主。它会调用 find_where_to_watch，将当前服务商列表与 JSON 快照进行比较，并生成 Markdown 差异报告，显示新增、移除、未变更和缺失的服务商可用性。

本地 stdio MCP：

npm run build
set -a && source ./.env && set +a && npm run demo:provider-monitor -- --country US --titles "The Matrix,Inception" --services "Netflix,Prime Video"

由 Cloudflare 托管的 MCP：

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/provider-change-monitor.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --country US --titles "The Matrix,Inception" --services "Netflix,Prime Video"

脚本会写入：

examples/provider-change-monitor.md
examples/provider-change-snapshot.json

收藏集缺口查找器

收藏集缺口查找器脚本现已调用升级后的 MCP 工具 build_collection_gap_plan，并生成可重复执行的 Markdown 完成报告，其中包含已观看条目、缺失条目、剩余时长、服务商可用性，以及最短完成路径。

本地 stdio MCP：

npm run build
set -a && source ./.env && set +a && npm run demo:collection-gaps -- --franchise "The Matrix" --watched "The Matrix" --country US --services "Netflix,Prime Video"

由 Cloudflare 托管的 MCP：

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/collection-gap-finder.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --franchise "The Matrix" --watched "The Matrix" --country US --services "Netflix,Prime Video"

脚本会写入：

examples/collection-gap-finder.md

Cloudflare Workers 上的远程 MCP

此仓库也可以在 Cloudflare Workers 上作为远程 MCP 服务运行。远程服务通过 Streamable HTTP 在 /mcp 暴露相同的 TMDB 工具，因此 Claude、Cowork、Claude Desktop 连接器和其他远程 MCP 客户端都可以连接到一个公开 URL。

现有的本地 stdio 服务保持不变，供 Codex 和本地 Claude Desktop 使用。Cloudflare 入口文件为 src/worker.ts。

Worker 还会在 / 提供一个浏览器演示：周末观影礼宾。它支持独自观影推荐和观影派对模式，并使用 TMDB 的发现、热门、正在上映、演职人员、海报和观看平台数据，生成按排名排列的电影候选清单。浏览器应用还包含一个帮助抽屉，介绍 Cloudflare 的用法；以及一个工作流演示面板，其中提供了脚本优先型产物的命令，例如每周流媒体雷达、平台变更监控和收藏缺漏查找器。

浏览器演示还包含一个 MCP 工具面板，可调用已部署的 /mcp 路由，验证预期的工具契约，并抽样调用 compare_movies、find_where_to_watch、get_weekend_watchlist、plan_watch_party、build_franchise_watch_order、build_collection_gap_plan、recommend_from_taste_profile 和 build_person_watch_path。

有关完整的浏览器应用、已部署的 Worker、访问令牌和 MCP 交接，请参阅 docs/weekend-watch-concierge.md。

部署

1. 登录 Cloudflare：

   npx wrangler login
   

2. 将 TMDB 密钥保存为 Worker 密钥：

   npx wrangler secret put TMDB_API_KEY
   

3. 在分享部署之前，将访问令牌保存为 Worker 密钥：

   npx wrangler secret put ACCESS_TOKEN
   

   设置 ACCESS_TOKEN 后，POST /api/concierge 和 POST /mcp 需要：

   Authorization: Bearer <your-access-token>
   

4. 检查 Worker 包：

   npm run worker:dry-run
   

5. 部署：

   npm run worker:deploy
   

Cloudflare 会输出类似这样的 URL：

https://tmdb-mcp.<your-workers-subdomain>.workers.dev

在远程客户端中使用此 MCP 端点：

https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp

使用此浏览器演示 URL：

https://tmdb-mcp.<your-workers-subdomain>.workers.dev/

从 Claude / Cowork 连接

对于 Claude 自定义连接器：

1. 打开 Claude 设置：Customize -> Connectors。
2. 点击 + -> Add custom connector。
3. 使用已部署的 Worker MCP URL：

   https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp
   

4. 在对话中启用此连接器，并提出 TMDB 相关问题，例如：

   What movies are trending this week?
   

对于仍需要本地命令的 Claude Desktop 版本或 MCP 客户端，请使用 mcp-remote 代理：

{
  "mcpServers": {
    "tmdb-remote": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp"
      ]
    }
  }
}

安全说明

如果未配置 ACCESS_TOKEN，Worker 不启用身份验证，方便个人测试。任何拥有 Worker URL 的人都可以调用只读 TMDB 工具，并消耗你的 TMDB API 配额。将 ACCESS_TOKEN 保持为已配置状态，或在将其分享给自己的账号以外的人之前使用 Cloudflare Access。

周末观影顾问

运行离线顾问测试：

npm test

此命令会构建 TypeScript 项目、启动一个小型本地 TMDB 兼容测试服务器，并验证 createWeekendConcierge 是否会将符合指定流媒体服务的影片排在首位，同时遵守运行时筛选条件。无需 TMDB API 密钥。

在本地运行 Worker：

npm run worker:dev

此命令会将 .env 中的本地值同步到未跟踪的 .dev.vars 文件，以便 Wrangler 在本地开发期间向 Worker 提供 TMDB_API_KEY。

如需在本地进行受保护的测试，请将 ACCESS_TOKEN 添加到 .env。浏览器应用包含访问令牌输入框，冒烟测试脚本可以从 shell 环境中读取 ACCESS_TOKEN 或 TMDB_MCP_ACCESS_TOKEN。

打开：

http://127.0.0.1:8787/

本地 Worker 运行后，对顾问 API 进行冒烟测试：

npm run smoke:concierge

对远程 MCP 端点进行冒烟测试，并调用面向 Agent 的顾问工具：

node scripts/remote-mcp-smoke.mjs http://127.0.0.1:8787/mcp --call-concierge

对于受保护的部署：

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/remote-mcp-smoke.mjs https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --call-concierge

或者测试已部署的 Worker：

node scripts/concierge-smoke.mjs https://tmdb-mcp.<your-workers-subdomain>.workers.dev

此应用使用：

• POST /api/concierge 获取排序后的影片推荐
• POST /api/collection-gap-plan 获取 Planning Lab 的系列影片观看缺口规划
• POST /api/taste-profile 获取 Planning Lab 的口味匹配推荐
• POST /api/person-watch-path 获取 Planning Lab 的人物观影路径
• GET /health 检查部署状态
• POST /mcp 供远程 MCP 客户端使用

Agent 可以调用 get_weekend_watchlist，参数包括：

• mood：crowd、thriller、thoughtful、funny、family 或 mindbend
• country：观看服务所在地区，例如 IN 或 US
• language：原始语言代码，例如 en、hi、ta、te 或 any
• runtime：最长时长（分钟），例如 120、150 或 any
• minRating：TMDB 最低评分
• services：偏好的流媒体服务
• familySafe：设为 true，在 TMDB 提供类型数据时排除常见的成人类型

如果需要为一群人做决定，Agent 可以调用 plan_watch_party。参数包括：

• moods：从 crowd、thriller、thoughtful、funny、family 或 mindbend 中选择 1 到 3 个值
• groupSize：观看人数
• country、language、runtime、minRating 和 services：含义与周末观影清单中的相同
• avoidTitles：群组已经看过或希望排除的影片
• familySafe：设为 true，在 TMDB 提供类型数据时排除常见的成人类型

Agent 可以调用 build_franchise_watch_order 获取系列影片或电影宇宙指南。参数包括：

• query：系列或合集名称，例如 The Matrix、Dune、Batman 或 Mission Impossible
• country：观看服务所在地区，例如 IN 或 US
• maxMovies：要包含的合集条目数上限，介于 2 到 20 之间

Agent 可以调用 build_collection_gap_plan 规划如何补完系列影片。参数包括：

• query：系列或合集名称
• watchedTitles：已观看的影片名称或 TMDB 电影 ID
• country：观看服务所在地区，例如 IN 或 US
• services：偏好的流媒体服务
• maxMovies：要包含的合集条目数上限，介于 2 到 20 之间

Agent 可以调用 recommend_from_taste_profile 获取个性化推荐。参数包括：

• likedTitles：用户喜欢的 1 到 5 部影片
• dislikedTitles：可选，用户不喜欢或希望在风格上避开的影片
• country、services、language、runtime 和 minRating：筛选条件和立即观看偏好
• maxResults：要返回的推荐数量，介于 3 到 10 之间

Agent 可以调用 build_person_watch_path 查询演员、导演、编剧或剧组成员的作品。参数包括：

• name：人物姓名，例如 Keanu Reeves 或 Christopher Nolan
• country：观看服务所在地区，例如 IN 或 US
• services：偏好的流媒体服务
• maxTitles：要返回的观影路径条目数，介于 3 到 8 之间

Cloudflare MCP 演示工作流

如需体验具体的端到端 Agent 工作流，请运行正在上映影片的后续演示。它会像远程客户端一样使用 MCP 服务：

1. 使用 get_now_playing，在选定地区发现当前正在上映的影片
2. 使用 get_movie_details 获取所选影片的详情
3. 使用 get_watch_providers 查询可立即观看的渠道
4. 使用 get_recommendations 获取推荐；对于非常新的影片，则回退使用 get_similar_movies
5. 使用 get_watch_providers 检查后续影片的观看渠道

本地 stdio MCP：

npm run build
set -a && source ./.env && set +a && npm run demo:now-playing -- --region US

由 Cloudflare 托管的 MCP：

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/now-playing-follow-on-demo.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --region US

脚本会将最终产物写入此处：

examples/now-playing-follow-on-demo.md

npm run install:local 的作用

安装程序使用仓库提供的启动器 plugins/tmdb/scripts/run-server.sh。

对于 Codex，它会：

• 将启动器注册为 MCP 服务
• 安装本地 TMDB 插件负载，使其显示在插件界面中

对于 Claude Desktop，它会：

• 将同一启动器注册为本地 MCP 服务

它会更新：

• ~/.codex/config.toml
• ~/.codex/.tmp/plugins/.agents/plugins/marketplace.json
• ~/.codex/plugins/cache/openai-curated/tmdb/...
• ~/Library/Application Support/Claude/claude_desktop_config.json

启动器会从 shell 环境或仓库的 .env 文件中读取 TMDB_API_KEY。

在 Claude Desktop 中使用

如果你倾向于手动设置，请将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "tmdb-local": {
      "command": "/full/path/to/mcp-server-tmdb/plugins/tmdb/scripts/run-server.sh",
      "args": []
    }
  }
}

编辑配置后，重启 Claude Desktop。

在 Codex 中使用

安装程序会将以下配置块添加到 ~/.codex/config.toml：

[mcp_servers.tmdb_local]
command = "/full/path/to/mcp-server-tmdb/plugins/tmdb/scripts/run-server.sh"

[plugins."tmdb@openai-curated"]
enabled = true

编辑配置后，重启 Codex。在全新的 Codex 会话中，TMDB 应会出现在插件列表中，并提供 mcp__tmdb__ 命名空间。

验证

离线冒烟测试：

TMDB_API_KEY=dummy node plugins/tmdb/scripts/smoke-test.mjs

在线冒烟测试：

set -a && source ./.env && set +a && node plugins/tmdb/scripts/smoke-test.mjs --online

插件文档

有关插件打包、本地安装行为以及 Codex 专属说明，请参阅 plugins/tmdb/README.md。

在 BizClaw / NanoClaw 中使用

已内置于 Agent 容器中。只需在 .env 文件中设置 TMDB_API_KEY，无需配置。

示例提示词

"What's trending in movies this week?"
"Find me Thriller movies from 2023"
"Who is Christopher Nolan and what has he directed?"
"Where can I watch Inception in India?"
"Get details for movie ID 550 (Fight Club)"
"Find movies similar to Interstellar"
"What are the trending TV shows right now?"

许可证

MIT