TMDB MCP 服务器

一个用于 The Movie Database (TMDB) API 的 MCP 服务器。它为 Codex 和 Claude Desktop 等助手提供电影和电视搜索、流媒体可用性、演职人员详情以及推荐功能。

工具

电影发现

• get_weekend_watchlist — 根据心情、国家、语言、时长、评分和服务排名的周末精选列表

• search_movies — 按标题/关键词搜索 → 标题、ID、评分、概述

• get_trending — 前 10 名热门电影 (timeWindow: "day" | "week")

• get_weekly_trending_by_language — 按原始语言分组为英语、印地语和泰卢固语的每周热门电影

• search_by_genre — 按流派名称搜索电影，可选年份过滤器

• advanced_search — 按流派、年份、最低评分、排序、语言进行筛选

• search_by_keyword — 按主题/关键词查找电影（例如 "zombie", "heist"）

电影详情

• 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 获取完整简介 + 影视作品列表（电影 + 电视）

资源

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

Related MCP server: Usher MCP

快速入门

1. 在 themoviedb.org 获取 TMDB API 密钥 → 账户设置 → API

2. 克隆、安装并构建：

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

3. 创建本地 env 文件并添加您的 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。

本地 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。

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 还会在 / 提供一个浏览器演示：周末观看礼宾服务 (Weekend Watch Concierge)。它询问心情、国家、语言、时长、评分和流媒体服务，然后使用 TMDB 发现、热门、正在上映、演职人员、海报和观看提供商数据构建排名的电影短名单。

浏览器演示还包括一个 MCP 工具表面面板，它调用已部署的 /mcp 路由，验证预期的工具契约，并对 compare_movies、find_where_to_watch 和 get_weekend_watchlist 进行采样。

有关完整的浏览器应用、已部署的 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 端点进行烟雾测试并调用面向代理的礼宾工具：

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 用于排名电影推荐

• GET /health 用于部署健康检查

• POST /mcp 用于远程 MCP 客户端

代理可以使用以下参数调用 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: 首选流媒体服务

Cloudflare MCP 演示工作流

对于具体的端到端代理工作流，请运行正在上映的后续演示。它像远程客户端一样使用 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 插件负载，使其出现在插件 UI 中

对于 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 的使用

内置于代理容器中。只需在您的 .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