tmdb-mcp-server

---

概览

由 The Movie Database（TMDB）提供电影和电视节目元数据。按名称搜索影片和人物，获取完整演职员表和作品列表，按筛选条件发现影片，追踪热门内容，并查看所在地区的流媒体播放渠道。

工具

工具	描述
tmdb_search_titles	按名称搜索电影、电视节目和人物。必需的第一步：将名称解析为详情工具所需的整数 id。
tmdb_get_movie	一次调用获取完整电影详情，包括剧情简介、片长、类型、美国分级、预算／收入、演员、剧组、预告片、推荐内容、关键词和外部 id。
tmdb_get_show	获取完整电视节目详情，包括概述、播出日期、状态、季／集数、创作者、电视网、各季摘要、演员、预告片和内容分级。
tmdb_get_season	获取某一季的剧集列表，包括名称、播出日期、片长、平均投票分数、剧照、每集客串演员，以及该季的常驻演员。
tmdb_get_person	获取人物详情和完整作品列表，包括传记、生卒日期、combined_credits 中的演员／剧组列表，以及跨平台外部 id。
tmdb_discover_titles	按筛选条件和排序方式发现电影或电视节目，支持强大的查询条件：类型、日期／评分范围、最低投票数、演员／剧组／电视网、观看服务提供商、片长和排序方式。
tmdb_get_trending	获取当天或当周热门的电影、电视节目或人物。
tmdb_get_watch_providers	查看指定地区的流媒体可用情况（JustWatch），包括订阅／租借／购买／含广告／免费服务提供商列表及 TMDB 链接。必须提供地区代码。

资源

资源	描述
tmdb://movie/{movie_id}	按 ID 获取电影详情，作为可注入的上下文——与 tmdb_get_movie 返回的丰富记录相同。
tmdb://tv/{series_id}	按 ID 获取剧集详情——与 tmdb_get_show 返回的丰富记录相同。
tmdb://person/{person_id}	人物详情，包含前 50 条演职员表记录及完整总数；如需更多页面，请使用 tmdb_get_person。

功能参考

tmdb_search_titles _工具

• multi 模式（默认）混合搜索电影、剧集和人物，并使用 media_type 标注类型；movie、tv 或 person 可将结果限制为一种类型
• 可选参数包括 year（适用于 movie/tv 模式）、language、include_adult 和 page；无结果时会正常返回并提供恢复建议
• 每条结果都包含 id、media_type、标题/名称、release_year、overview、vote_average、genre_names 以及海报或头像 URL

---

tmdb_get_movie _工具

• 一次调用即可返回演职员表、视频、推荐内容、相似内容、关键词、外部 ID 和发行日期；可精简 append 数组（例如 ["credits"]）以缩小响应内容
• 包含美国分级、主要演员、核心幕后人员，以及带观看 URL 的 YouTube 预告片
• 不提供流媒体播放信息；请使用 tmdb_get_watch_providers

---

tmdb_get_show _工具

• append 选项与 tmdb_get_movie 相同，但用 content_ratings（美国电视分级）替代 release_dates
• 还会返回季摘要、创作者、电视网，以及最近播出/即将播出的剧集
• 从 seasons[] 传入 season_number，即可通过 tmdb_get_season 获取剧集列表

---

tmdb_get_season _工具

• 每集的名称、播出日期、时长、平均评分、剧照 URL 和客串演员
• 也会返回该季的常驻演员
• 输入中的 series_id 会原样返回；第 0 季为“特别篇”

---

tmdb_get_person _工具

• 个人简介、重要日期、出生地、知名领域、别名、性别和外部 ID（IMDb、Wikidata、社交账号）
• combined_credits 按 cast_credits 和 crew_credits 分类，并按时间从新到旧排序；credits_page（默认为 1）每页最多返回各 50 条，并在每页提供完整总数
• 如需更多内容，请继续查询 next_credits_page；超出末页的页面会返回空列表

---

tmdb_discover_titles _工具

• 可按 with_genres/without_genres、year 或 release_date_gte/lte 时间范围、vote_average 范围、vote_count_gte、with_cast/with_crew（电影）、with_networks（剧集）、with_watch_providers + watch_region、with_original_language 以及 runtime 范围筛选
• 可按热度、票房、平均评分、评分数或发行日期排序；将 vote_average.desc 与 vote_count_gte（约 100–1000）搭配使用，可避免低票数作品排在前面
• 不适用于该媒体类型的筛选条件会显示提示；未提供 watch_region 时使用 with_watch_providers 会返回 region_required

---

tmdb_get_trending _工具

• media_type：all（默认）混合返回电影、剧集和人物；也可限制为一种类型
• time_window：day 或 week（默认）
• 每页最多 20 条结果；可通过 page 获取更多内容；无结果时会正常返回并提供恢复建议

---

tmdb_get_watch_providers _工具

• 返回包月、租赁、购买、广告和免费服务提供商列表及其徽标 URL，以及 TMDB JustWatch 的 link
• 必须提供 watch_region（ISO 3166-1 alpha-2）；响应中始终会注明地区
• 结果为空表示该地区无法流媒体播放；提供商 ID 可用于 tmdb_discover_titles 中的 with_watch_providers

---

tmdb://movie/{movie_id} _资源

• 与 tmdb_get_movie 返回相同的记录——application/json
• movie_id 来自 tmdb_search_titles 或 tmdb_discover_titles
• 当 TMDB 针对该 ID 返回 404 时，会返回类型化的 movie_not_found 错误

---

tmdb://tv/{series_id} _资源

• 与 tmdb_get_show 返回相同记录 — application/json
• series_id 来自 tmdb_search_titles 或 tmdb_discover_titles
• 当 TMDB 对该 ID 返回 404 时，返回类型化的 show_not_found 错误

---

tmdb://person/{person_id} _资源

• 人物详情，包含前 50 条演员演职记录和前 50 条幕后演职记录，以及完整总数 — application/json；如需后续页面，请使用 tmdb_get_person
• person_id 来自 tmdb_search_titles（模式为 "person"）
• 当 TMDB 对该 ID 返回 404 时，返回类型化的 person_not_found 错误

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

TMDB 专属功能：

• 用于 TMDB v3 REST API 的类型化客户端，使用 v4 Read Access Token 进行身份验证
• 将图片路径解析为完整图片 URL；缺失路径时省略该字段
• 将类型 ID 解析为类型名称，因此无需额外调用即可读懂列表结果
• 详情工具通过一次请求返回演职人员、视频、推荐内容、关键词和外部 ID
• 由 JustWatch 提供支持的区域感知流媒体播放可用性；区域始终是明确的输入

便于 Agent 使用的输出：

• 每条响应的 enrichment.attribution 中都包含 TMDB 署名信息
• 列表响应包含总数、页码/总页数，以及实际应用的筛选条件说明
• 无结果时正常返回并提供恢复指引，而不是作为错误返回
• 观看服务商结果始终注明区域；达到数量上限的影视作品列表会显示完整总数

开始使用

需要 TMDB API Read Access Token。创建免费的 TMDB 账户，然后从API 设置中复制 API Read Access Token（v4 JWT）——此服务使用 Authorization: Bearer <token> 对 v3 端点进行身份验证，而非使用旧版 ?api_key= 查询参数。

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "tmdb-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/tmdb-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "TMDB_API_KEY": "your-tmdb-read-access-token"
      }
    }
  }
}

或者使用 npx（无需 Bun）：

{
  "mcpServers": {
    "tmdb-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/tmdb-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "TMDB_API_KEY": "your-tmdb-read-access-token"
      }
    }
  }
}

或者使用 Docker：

{
  "mcpServers": {
    "tmdb-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "TMDB_API_KEY=your-tmdb-read-access-token",
        "ghcr.io/cyanheads/tmdb-mcp-server:latest"
      ]
    }
  }
}

对于 Streamable HTTP，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 TMDB_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

先决条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• TMDB API Read Access Token（v4 JWT）——可从 TMDB API 设置免费获取。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/tmdb-mcp-server.git

2. 进入目录：

cd tmdb-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set TMDB_API_KEY

配置

所有配置都会在启动时通过 Zod 模式进行验证。主要环境变量：

变量	描述	默认值
TMDB_API_KEY	必需。 TMDB v4 API Read Access Token（JWT）。	—
TMDB_LANGUAGE	默认响应语言（例如 en-US）；单次调用中的 language 会覆盖此设置。	en-US
TMDB_DEFAULT_REGION	在缺少 watch_region 时提示中显示的区域；不会应用于查询。	US
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOG_TOOL_FAILURE_PAYLOADS	记录失败工具的参数和结果；按键名脱敏，并限制在 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES 指定的大小以内（默认值为 16384）。自由格式的值可能包含机密信息。	false
STORAGE_PROVIDER_TYPE	存储后端。	in-memory
OTEL_ENABLED	启用 OpenTelemetry 监测（跨度、指标、完成日志）。	false
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	OTLP 日志端点。	—

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t tmdb-mcp-server .
docker run --rm -e TMDB_API_KEY=your-token -p 3010:3010 tmdb-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/tmdb-mcp-server。默认会安装 OpenTelemetry 对等依赖项——如需省略这些依赖项，请使用 --build-arg OTEL_ENABLED=false 构建。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具和资源。
src/config	使用 Zod 解析并验证服务专属的环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）——八个 TMDB 工具。
src/mcp-server/resources	资源定义（*.resource.ts）——电影、电视和人物详情。
src/services/tmdb	TMDB v3 REST 客户端。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 AGENTS.md（或内容相同的 CLAUDE.md。简要说明：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求级日志，使用 ctx.state 存储租户级数据
• 通过 src/mcp-server/*/definitions/index.ts 中的 barrels 注册新工具和资源

致谢

本产品使用 TMDB API，但未获 TMDB 背书或认证。流媒体可用性数据由 JustWatch 通过 TMDB 提供，并因地区而异。

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。