TMDB MCP Server

TMDB MCP 服务

一个用于 The Movie Database (TMDB) 的 MCP 服务：搜索和查询电影、电视剧及人物，并在同一次调用中读取 IMDb / Rotten Tomatoes / Metacritic 评分（通过 OMDb）。

该服务通过标准 MCP stdio 通信，因此适用于任何 MCP 客户端 （Claude Desktop/Code、Cursor、VS Code、Cline，……）。

连接后，只需用自然语言向你的 Agent 提问（需要免费的 TMDB 令牌；请参阅获取凭据）：

"Search for the movie Dune: Part Two and show its overview, genres and runtime."
"What movies are trending this week?"
"Find TV shows similar to Breaking Bad."
"Who directed Oppenheimer? Show the main cast."
"What's Greta Gerwig's filmography?"
"Discover highly-rated sci-fi movies from the 2010s, sorted by rating."
"Where can I stream The Bear in the US?"
"Show me the trailer for Deadpool & Wolverine."
"List the episodes of Severance season 1."
"Which movie has IMDb id tt0111161?"
"Search for people named Zendaya."
"Get the year, genres and rating for these five movies in one go: Dune, Dune: Part Two, Arrival, Sicario and Blade Runner 2049."
"What are the best limited series to binge over a weekend?"
"What TV shows can I watch with my 9-year-old kid?"
"What movies has A24 produced?"
"What are Tarantino's best-rated crime movies?"
"Who composed the music for My Neighbor Totoro, and what else has he scored?"

使用可选的（免费）OMDb 密钥后，也会添加评分：

"What are the IMDb, Rotten Tomatoes and Metacritic scores for The Godfather?"
"Compare the critics' scores for Barbie and Oppenheimer."

安装

将它添加到 MCP 客户端的配置中。唯一必需的凭据是 TMDB v4 Read Access Token；OMDB_API_KEY（评分）和 TMDB_LANGUAGE / TMDB_REGION （本地化）为可选项。

通过 npx（无需安装）：

{
  "mcpServers": {
    "tmdb": {
      "command": "npx",
      "args": ["-y", "tmdb-mcp"],
      "env": {
        "TMDB_API_TOKEN": "your-tmdb-v4-read-access-token (required)",
        "OMDB_API_KEY": "your-omdb-key (optional: IMDb/RT/Metacritic ratings)",
        "TMDB_LANGUAGE": "en-US (optional: localize, e.g. ru-RU)",
        "TMDB_REGION": "US (optional: region for certifications, e.g. RU)"
      }
    }
  }
}

请将每个值替换为你自己的值。只需设置 TMDB_API_TOKEN；如果不需要可选项，请删除标记为可选的行。

作为 .mcpb 捆绑包安装（Claude Desktop 最简单的方式）： 从最新版本 下载 tmdb-mcp.mcpb，然后打开它，或将其拖到 Claude Desktop 的扩展中。这是一个独立的 捆绑包（无需 Node 或 npm）；在安装对话框中输入令牌和可选字段。更新时重新下载并安装。

从源代码安装： git clone，然后运行 npm ci && npm run build，并通过 "command": "node"、 "args": ["/ABS/PATH/tmdb-mcp/dist/index.js"] 和与上文相同的 env 将客户端指向它。

有关各客户端的详细信息和所有可调参数，请参阅 docs/clients.md。

功能

工具	用途
search_movies / search_tv / search_people	按名称查找影片/人物 → TMDB id
search_multi	同时搜索电影、电视节目和人物（每行都有一个 media_type）
get_movie / get_tv	完整详情 + IMDb/RT/Metacritic 评分（通过 include_ratings 切换）
get_movies / get_tv_shows	为 1-20 个 id 一次调用获取精简卡片（标题/年份/类型/平均评分，可选获取评分）
get_person	传记、部门、链接
get_movie_credits / get_tv_credits	主要演员和核心剧组（电视节目：涵盖全部播出集数，按出演集数排序）
get_movie_recommendations / get_tv_recommendations	根据共同观看数据提供推荐（粉丝还喜欢哪些作品）
get_similar	通过算法查找相似作品（media_type + id）
get_trending	当前热门内容（电影 / 电视节目 / 人物，按日或周统计）
get_movie_releases	某个国家当前在影院上映（now_playing）或即将上映（upcoming）的电影，采用 TMDB 的日期范围
get_movie_genres / get_tv_genres	类型 id ↔ 名称对照
discover_movies	按类型、日期范围、评分、演员/剧组、公司、原产国、关键词、服务商（+/-、访问类型）、分级和地区上映日期筛选
discover_tv	同上，还可按电视网/类型/状态和日期范围内播出的剧集筛选；但不支持按演员/剧组/人物或地区上映日期筛选（人物请使用 get_person_credits）
get_watch_providers	按地区查询可观看的流媒体、租赁或购买渠道（通过 TMDB 获取 JustWatch 数据）
get_person_credits	某个人的影视作品列表（演员和剧组）
get_videos	预告片/先导预告/片段（YouTube 链接）
get_reviews	电影/电视节目的用户评论（作者、评分、文本）
get_collection	电影系列/合集及其组成作品，按上映顺序排列
find_by_imdb_id	将 IMDb id 转换为 TMDB 电影/电视节目/人物
get_tv_season / get_tv_episode	季剧集列表 / 单集详情
search_keywords	将关键词名称转换为 discover_* 所需的 id
search_companies	将制作公司名称转换为 discover_* 的 with_companies 所需的 id
search_collections	将系列名称（例如 'harry potter'）转换为 get_collection 所需的合集 id
search_watch_providers	将流媒体/租赁服务名称（例如 'Netflix'）转换为 discover_* 的 with_watch_providers 所需的 id
get_ratings	按 IMDb id 或标题查询 IMDb/RT/Metacritic 评分（独立查询）
提示词。 除上述工具外，服务还提供两个 MCP 提示词：
recommend_similar（title、可选的 media_type、可选的 count）会规划一项搜索，查找与用户喜欢的作品相似的标题，并调用 get_similar /
get_movie_recommendations / get_tv_recommendations / discover_movies /
discover_tv，而不是依赖模型自身的知识。top_by_entity
（name、可选的 entity_type、genre、media_type、count）会通过 discover_movies/
discover_tv 查找某个人或制作公司／制片厂评价最高的作品（例如“A24 最佳电影”或“塔伦蒂诺最佳犯罪片”）；对于某人的电视作品，则会专门回退到
get_person_credits（TMDB 自带的 /discover/tv 完全无法按人物筛选）。

核心数据源与补充信息。 TMDB 是主要数据源（搜索、元数据、人物、趋势）。OMDb 是可选的补充数据源：get_movie/get_tv 会将 TMDB 返回的 imdb_id 用于查询 OMDb，因此一次调用即可获得评分和奖项摘要自由文本（主要奖项的获奖／提名情况，例如电影的奥斯卡奖或剧集的艾美奖；针对作品整体，而非归属于某个人），以及 OMDb 自带的年龄分级（ratings.rated，与此服务自身的 certification 不同）。不设置 OMDb 密钥时，TMDB 数据仍可正常使用；ratings 字段只会报告尚未配置。

本地化。 设置 TMDB_LANGUAGE（例如 ru-RU）和 TMDB_REGION（例如 RU），即可获取本地化的标题／简介／类型名称以及特定地区的分级信息。search_movies/search_tv/search_multi/search_people/ search_collections、get_movie/get_tv/get_movies/get_tv_shows/get_person、 get_collection、get_movie_releases 和 discover_movies/discover_tv 也 支持为单次调用指定 language 覆盖值。

获取凭据

需要一个令牌（TMDB）；OMDb 密钥为可选项。两者均可免费获取。

1. TMDB 令牌（必需）。 在 themoviedb.org 创建免费账户，然后打开 设置 → API 并申请 API 密钥（个人用途）。将 “API Read Access Token”（较长的 v4 令牌，而非 较短的 v3 密钥）复制到 TMDB_API_TOKEN。它会以 Authorization: Bearer … 的形式发送。
2. OMDb 密钥（可选）。 在 omdbapi.com/apikey.aspx 获取免费密钥（免费套餐即可），点击邮件中的激活链接，并设置 OMDB_API_KEY。这样即可在电影和电视详情中获取 get_ratings 以及 IMDb / Rotten Tomatoes / Metacritic 评分。不设置此密钥，其他功能仍可正常使用。

将这些值放入 MCP 客户端配置的 env 块中（各客户端的配置示例请参见 docs/clients.md）。切勿提交这些值。 TMDB_LANGUAGE / TMDB_REGION 可选，用于设置默认语言／地区（例如 ru-RU、RU）。

高级调优（仅限环境变量，无安装界面对应选项）

默认值通常已足够；只有确认需要时才设置。只能通过环境变量设置，不会显示在 Claude Desktop 的安装表单中，因此 CLI/Docker 用户需直接设置。

变量	默认值	用途
TMDB_BASE_URL	https://api.themoviedb.org/3	覆盖 TMDB 的 API 基础 URL（例如代理）
OMDB_BASE_URL	https://www.omdbapi.com	覆盖 OMDb 的 API 基础 URL
HTTP_TIMEOUT_MS	15000	中止请求前的单次请求超时时间
HTTP_RETRIES	2	上游发生暂时性故障时的重试次数
TMDB_MIN_INTERVAL_MS	60	TMDB 请求之间的最小间隔
OMDB_MIN_INTERVAL_MS	0	OMDb 请求之间的最小间隔
CACHE_TTL_MS	300000	缓存响应保持有效的时长
LOG_LEVEL	info	debug | info | warn | error | silent

如果 TMDB/OMDb 短暂不可用，且工具改为返回缓存的过期响应而非失败，结果会在常规数据旁附带 _meta: {"tmdb-mcp/stale": true}，以便客户端区分降级结果和最新结果。

开发

npm install
npm run build        # type-check + bundle to dist/index.js
npm test             # node:test (mocked, offline)
npm run lint
npm run format
npm run check:api    # live upstream health-check (needs the env credentials)
npm run inspector    # run under the MCP Inspector

运行环境需要 Node ≥ 22.18。贡献者/Agent 指南见 AGENTS.md。

更新

• .mcpb bundle： 从 releases 页面下载新版 bundle 并重新安装。
• 从源代码更新： git pull && npm ci && npm run build。
• npx： 未固定版本的 npx -y tmdb-mcp 会在下次运行时获取最新版。

本产品使用 TMDB API，但未经 TMDB 认可或认证。

隐私政策

tmdb-mcp 完全在你自己的机器上运行，不会自行收集任何数据。 请参阅 PRIVACY.md，了解它具体会向 TMDB/OMDb 发送哪些内容，以及会在本地存储哪些内容（如果有）。

安全

只读，仅连接两个固定的上游主机，不会持久保存凭据。完整说明及漏洞报告方式，请参阅 SECURITY.md。

许可证

MIT © Grinv