TMDB MCP 服务器

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

工具

电影发现

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

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

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

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

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

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

电影详情

• get_movie_details — 完整详情：演职人员、时长、类型、评论（按 movieId）

• get_recommendations — 基于电影 ID 的前 5 名推荐

• get_similar_movies — 通过 TMDB 的相似度算法查找相似电影

• get_watch_providers — 按国家/地区查询流媒体/租赁/购买可用性（默认：IN）

电视节目

• 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: TMDB MCP Server

快速入门

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__ 命名空间。

在 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 发现、热门、正在上映、演职人员、海报和观看提供商数据构建一个排名的电影精选列表。

有关完整的浏览器应用、已部署的 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。

周末观影礼宾 (Weekend Watch Concierge)

在本地运行 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: 首选流媒体服务

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