tvmaze-mcp-server

---

概述

来自 TVmaze 的电视数据：剧集、剧集指南、演员阵容和播出时间。按标题或 IMDb/TheTVDB ID 查找剧集，查看下一集在您所在时区的播出时间，或查询任意日期播出和上线的内容。无需 API 密钥。

工具

工具	描述
tvmaze_search_shows	模糊搜索剧集标题，最多返回 10 部剧集，以及频道、状态、类型、评分和外部目录 ID
tvmaze_get_show	某个 TVmaze ID 的完整资料——每周播出时段、季列表以及上一集和下一集
tvmaze_lookup_show	根据 IMDb、TheTVDB 或 TVRage ID 查找剧集，并返回匹配的 TVmaze 资料
tvmaze_get_next_episode	按 TVmaze ID 或标题查询剧集下一集的播出时间，并转换为观众所在时区
tvmaze_get_episodes	某一季、某个播出日期或整部剧集的剧集指南，包含播出时间、时长和剧情简介
tvmaze_get_schedule	查询某日播出的剧集——某个国家的广播和有线电视网络、流媒体服务，或两者兼有
tvmaze_get_cast	查询剧集的演职人员及其饰演的角色，可选包含剧组成员；也可查询某集的客串演员，并可选包含导演和编剧
tvmaze_get_person	搜索人物姓名以查找候选人，或分页查询某人的主演、客串或剧组成员作品

功能参考

tvmaze_search_shows _工具

• 将 query 与所有节目标题进行模糊匹配，因此轻微拼写错误仍可匹配；不接受空白标题
• 最多返回 10 个节目，不支持分页；输出会报告 shown / cap，并在结果已满或为空时建议改用更具体的标题或 tvmaze_lookup_show
• 每个条目都包含通用节目摘要以及 match_score；该分数仅适用于同一结果集内的比较

---

tvmaze_get_show _工具

• show_id 可来自 tvmaze_search_shows、tvmaze_lookup_show 或排期条目；可选 IANA timezone，用于表示剧集播出时间
• 返回完整资料（schedule_days / schedule_time、可选的 schedule_timezone、official_site、externals）、所有季，以及 next_episode / previous_episode。对于尚无已公布内容的 Running 节目，响应会附带提示，指向 previous_episode
• 未知的 show_id 会以 show_not_found 报错

---

tvmaze_lookup_show _工具

• source 可以是 imdb（tt ID）、thetvdb 或 tvrage（已停用，仅存在于较旧的记录中），并与 external_id 配对
• IMDb ID 也接受纯数字、大写 TT 和 imdb.com 标题 URL
• TVmaze 中不存在的节目会作为查询结果返回，而不是报错：found: false，并附带引导至 tvmaze_search_shows 的 guidance。匹配成功时会回显 source 和 external_id，并返回与搜索结果相同的节目摘要

---

tvmaze_get_next_episode _工具

• by: "id" 接受 TVmaze ID；by: "title" 会通过比 tvmaze_search_shows 更严格的单项匹配搜索来解析非空白标题
• 播出时间会按请求的 IANA timezone 显示；time_known: false 表示尚未公布具体时间，因此只有日期可靠
• 未匹配结果会包含类型化的 miss_reason：show_not_found（标题）或 no_scheduled_episode（两季之间，附带 previous_episode）。无法解析的 show_id 会抛出 show_not_found_by_id

---

tvmaze_get_episodes _工具

• season 用于列出某一季；air_date（YYYY-MM-DD）用于列出某一天的剧集；两者都省略则列出完整播出记录。两者不能同时使用。某一天没有剧集时会返回空列表并附带提示；无效日期会以 invalid_date 报错；season_not_found 会列出已有季
• air_date 与来源中的 airdate 匹配；深夜时段的剧集，其 local_date 可能相差一天
• include_specials 默认为 false，每个列表都会报告过滤掉的特别篇数量。limit（默认 50，最大 250）设置每页大小；使用 next_cursor / has_more 继续浏览列表，totalCount 统计分页前的总数

---

tvmaze_get_schedule _工具

• scope 用于选择数据源：linear 是一个国家的广播和有线电视网及其本地流媒体服务；省略 country 时，streaming 表示全球服务，指定 country 时则表示该国的本地服务；all 会合并两者
• date 默认为所请求 timezone 中的当天；country 使用 ISO 3166-1 alpha-2 代码（英国为 GB），对于 linear 和 all，未指定时会回退到已配置的默认值；可选的 channel 会按频道名称进行精确且不区分大小写的筛选；limit 默认为 50（最大 250）
• 条目包含 feed（linear / streaming）和精简的 show 引用（tvmaze_get_show 会返回完整资料）。applied_feeds 列出成功响应的数据源，例如 ["linear:GB","web:GB","web:global"]；某个数据源失败时会附带提示，而不会导致整个调用失败

---

tvmaze_get_cast _工具

• scope: "show" 返回主要演员阵容及角色名称；scope: "episode" 返回该集的客串演员阵容。include_crew 会添加剧集的工作人员，或该集的客串工作人员（导演、编剧）
• 可选的 name 用于按表演者、角色或工作人员职务的子字符串筛选（只有在 include_crew: true 时才筛选工作人员）。结果按页返回，limit 默认值为 50，最大值为 250；使用 cursor 翻页；cast_total / crew_total 统计所有匹配的演职人员记录
• 演员记录包含 as_self 和 voice_only；工作人员记录包含 credit_type，且不包含角色。剧集的演员阵容列表不会区分常驻演员和客串演员，因此请检查某一集的客串演员阵容。缺失的演职人员记录会以提示形式返回，而非错误

tvmaze_get_person _工具

• 必须且只能提供 query（姓名搜索）或 person_id（来自演职人员记录或候选项）之一。搜索会返回包含来源评分的精简候选项，不会替你选定某人；十个候选项可能意味着已达到来源上限，请缩小姓名范围
• person_id 会返回该人物及一种 credit_kind：cast（默认）、guest 或 crew；limit（默认值为 50，最大值为 250）和 cursor 仅适用于此处。客串演职人员记录中的 episode_id 可接续调用 tvmaze_get_cast；show_id 可接续调用 tvmaze_get_show 或 tvmaze_get_episodes
• 没有候选项或演职人员记录时会返回空成功结果；找不到对应 ID 时会返回 person_not_found

功能特性

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

TVmaze 特有功能：

• 无需密钥：无需账户或 API 密钥，且所有工具在全新安装后无需任何配置即可使用
• 请求速率会控制在 TVmaze 的单 IP 限制以下；遇到 429 时会退避（遵循 Retry-After），并在进程内缓存结果
• 仅根据 airstamp 计算播出时间，因为夜间时段的 airdate / airtime 可能与实际时间相差整整一天
• 将社区编写的 HTML 简介转换为纯文本

适合 Agent 使用的输出：

• 不会虚构具体时间：未公布时间的记录会返回 time_known: false 和仅含日期的信息；缺失字段会显示为 Not available，而非 0 或 ""
• 每个工具都会返回类型化错误，其中包含 reason 和恢复提示
• 无匹配结果也会作为结果返回：tvmaze_lookup_show 和 tvmaze_get_next_episode 的标题参数分支会返回 found: false，并提供下一步调用的 guidance
• 输出会说明调用涵盖的内容：回显查询、applied_feeds、分页前总数，以及相对于来源上限的截断情况

数据与许可

数据来自 TVmaze，采用 CC BY-SA 许可。请注明 TVmaze 为来源，并保留每条剧集、单集和人物记录中包含的 url 字段——链接回来源即可满足署名要求。根据相同方式共享条款，基于这些数据改编的内容必须采用相同许可共享。

TVmaze 对每个 IP 地址至少限制为每 10 秒 20 次调用；超出此频率的突发请求会收到 HTTP 429 响应。服务会将请求速率控制在该限额以下，并在收到 429 时退避。上游会将输出缓存 60 分钟，因此日程变更或新公布的单集最多可能需要一小时才会显示；本地响应缓存（TVMAZE_CACHE_TTL_S，默认值为 300 s）远短于此时间。

开始使用

公共托管实例

公共实例位于 https://tvmaze.caseyjhand.com/mcp，无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

{
  "mcpServers": {
    "tvmaze-mcp-server": {
      "type": "streamable-http",
      "url": "https://tvmaze.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。无需 API 密钥。

{
  "mcpServers": {
    "tvmaze-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/tvmaze-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可通过 npx 运行（无需 Bun）：

{
  "mcpServers": {
    "tvmaze-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/tvmaze-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可通过 Docker 运行：

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

如需使用 Streamable HTTP，请设置传输方式并启动服务：

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

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 TVmaze 账号或 API 密钥。如果希望调用默认使用 UTC 和美国以外的时区和国家/地区，请设置 TVMAZE_DEFAULT_TIMEZONE 和 TVMAZE_DEFAULT_COUNTRY。

安装

1. 克隆代码仓库：

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

2. 进入目录：

cd tvmaze-mcp-server

3. 安装依赖：

bun install

4. 配置环境（可选）：

cp .env.example .env
# every variable is optional — edit only what you want to override

配置

变量	描述	默认值
TVMAZE_BASE_URL	TVmaze API 基础 URL。可覆盖此值以指向企业版端点。	https://api.tvmaze.com
TVMAZE_USER_AGENT	每次上游请求发送的 User-Agent；TVmaze 要求客户端标明自身身份。	服务名称、版本和代码仓库 URL
TVMAZE_DEFAULT_TIMEZONE	工具调用未提供 timezone 时使用的 IANA 时区。	UTC
TVMAZE_DEFAULT_COUNTRY	tvmaze_get_schedule 的 linear 和 all 范围在未提供 country 时使用的 ISO 3166-1 alpha-2 国家/地区代码。	US
TVMAZE_CACHE_TTL_S	上游响应在进程内缓存中的保留秒数。0 表示禁用缓存。	300
TVMAZE_MAX_CONCURRENCY	并发上游请求数（1–16）。	4
TVMAZE_REQUEST_TIMEOUT_MS	每个请求的超时时间，单位为毫秒（1000–120000）。	10000
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_HTTP_ENDPOINT_PATH	MCP 服务的挂载路径。	/mcp
MCP_SESSION_MODE	HTTP 会话模式；此服务始终为 stateless。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录失败工具调用的参数和结果（仅对键名进行脱敏）。	false
STORAGE_PROVIDER_TYPE	存储后端。	in-memory
OTEL_ENABLED	启用 OpenTelemetry 监测（跨度、指标、完成日志）。	false

完整的可选覆盖项列表请参见 .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 tvmaze-mcp-server .
docker run --rm -p 3010:3010 tvmaze-mcp-server

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

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册八个工具、服务说明和服务生命周期。
src/config	使用 Zod 解析并验证服务专用的环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）及其共用的输出架构。
src/services/tvmaze	TVmaze REST 客户端——负责请求节流、重试、响应缓存，以及将数据规范化为领域类型。
tests/	与 src/ 结构对应的单元测试和集成测试。
docs/	设计文档和生成的项目目录树。

开发指南

开发指南和架构规则请参见 CLAUDE.md/AGENTS.md。简要说明：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志；所有上游调用都必须经过 TvmazeService，处理程序中不得直接调用 fetch
• 在 src/index.ts 的 createApp() 数组中注册新工具
• 将上游边界逻辑保留在服务中：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段——缺少播出时间就应保持缺失

贡献

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

bun run devcheck
bun run test

许可证

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