tvmaze-mcp-server

---

概要

TVmaze のテレビ番組データを利用できます。番組、エピソードガイド、出演者、放送時刻を検索できます。タイトルまたは IMDb／TheTVDB の ID で番組を探したり、タイムゾーンに合わせて次回エピソードの放送日時を確認したり、任意の日に放送・配信された番組を調べたりできます。API キーは不要です。

ツール

ツール	説明
tvmaze_search_shows	曖昧検索でタイトルを検索し、チャンネル、放送状況、ジャンル、評価、外部カタログ ID とともに最大 10 件の番組を返します
tvmaze_get_show	1 つの TVmaze ID の詳細プロフィールを取得します。週間放送枠、シーズン一覧、前回と次回のエピソードを確認できます
tvmaze_lookup_show	IMDb、TheTVDB、または TVRage の ID から番組を特定し、対応する TVmaze プロフィールを取得します
tvmaze_get_next_episode	TVmaze ID またはタイトルを指定し、視聴者のタイムゾーンに変換して番組の次回エピソードの放送日時を取得します
tvmaze_get_episodes	1 シーズン、特定の放送日、または全エピソードのエピソードガイドを取得します。放送時刻、上映時間、あらすじを確認できます
tvmaze_get_schedule	指定日の放送エピソードを取得します。1 か国の地上波・ケーブルネットワーク、ストリーミングサービス、またはその両方を指定できます
tvmaze_get_cast	番組の出演者と役名を取得します。スタッフも指定できます。または、特定のエピソードのゲスト出演者と、任意で監督や脚本家を取得します
tvmaze_get_person	人名を検索して候補を取得するか、1 人の出演、ゲスト出演、またはスタッフとしてのクレジットをページ単位で取得します

機能リファレンス

tvmaze_search_shows _ツール

• すべての番組タイトルに対して query をあいまい検索するため、軽微なスペルミスがあっても一致します。空白のタイトルは除外されます
• 番組を最大10件返します。ページネーションはありません。出力には shown / cap が示され、結果がすべて一致する場合や空の場合は、より絞り込んだタイトルまたは tvmaze_lookup_show を案内します
• 各行には共通の番組概要と match_score が含まれます。スコアを比較できるのは同じ検索結果内のみです

---

tvmaze_get_show _ツール

• tvmaze_search_shows、tvmaze_lookup_show、または番組表の行から取得した show_id を指定します。エピソードの放送時刻には、オプションでIANA timezone を指定できます
• 全シーズンと next_episode / previous_episode を含む完全なプロフィール（schedule_days / schedule_time、任意の schedule_timezone、official_site、externals）を返します。放送中（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 を指定すると1シーズンのエピソード、air_date（YYYY-MM-DD）を指定すると1日分のエピソードを取得します。両方を省略すると全期間が対象になります。両者は併用できません。該当日のエピソードがない場合は通知と空のリストを返し、実在しない日付を指定すると invalid_date エラーになります。season_not_found では、存在するシーズンが示されます
• air_date はソースの airdate と照合されます。深夜帯の放送では、エピソードの local_date と1日ずれる場合があります
• include_specials のデフォルトは false で、各一覧には除外したスペシャル番組の件数が示されます。limit（デフォルト50、最大250）でページサイズを指定します。next_cursor / has_more で一覧を続けられ、totalCount はページ分割前の件数を示します

---

tvmaze_get_schedule _ツール

• scope で番組表を選択します。linear は1か国の地上波・ケーブルネットワークと国内ストリーミングサービス、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 _tool

• 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 _tool

• query（名前検索）または person_id（キャストのクレジットか候補から取得）のいずれか一方を指定してください。検索では、ソースのスコア付きの簡潔な候補が返され、候補が自動で選択されることはありません。候補が10件の場合、ソース側の上限に達している可能性があるため、名前を絞り込んでください
• person_id を指定すると、その人物と1つの credit_kind が返されます。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 キー不要です。アカウントも API キーも不要で、何も設定していない新規インストールでもすべてのツールが動作します
• TVmaze の IP ごとの制限を超えないようリクエスト間隔を調整し、429 では（Retry-After に従って）待機時間を延ばし、プロセス内にキャッシュします
• 深夜帯の放送枠では airdate / airtime が丸一日ずれる場合があるため、放送時刻は airstamp のみから算出します
• コミュニティ作成の HTML あらすじはプレーンテキストに変換されます

エージェントに適した出力：

• 時刻を捏造しません。発表済みの時刻がないレコードでは time_known: false と日付のみを返し、存在しないフィールドは 0 や "" ではなく Not available として出力します
• すべてのツールで型付きエラーを返します。各エラーには reason と復旧のヒントが含まれます
• 検索で見つからなかった場合も結果として返します。tvmaze_lookup_show と tvmaze_get_next_episode のタイトル指定では、次の呼び出しに向けた guidance とともに found: false を返します
• 呼び出しで対象となった内容を出力に示します。エコーされたクエリ、applied_feeds、ページ分割前の合計件数、ソースの上限に対する切り詰めの有無が含まれます

データとライセンス

データは TVmaze から取得しており、ライセンスは CC BY-SA です。出典として TVmaze を記載し、すべての番組、エピソード、人物のレコードに含まれる url フィールドを保持してください。リンクを戻すことが表示要件を満たす方法です。継承（ShareAlike）条項により、このデータを改変した場合は同じライセンスで共有する必要があります。

TVmaze は IP アドレスごとに少なくとも10秒間で20回の呼び出しを許可し、この上限を超える連続リクエストには HTTP 429 で応答します。このサーバーは上限内に収まるようリクエスト間隔を調整し、429 を受け取ると待機時間を延ばします。上流では出力が60分間キャッシュされるため、スケジュール変更や新たに発表されたエピソードが反映されるまで最大1時間かかる場合があります。ローカルのレスポンスキャッシュ（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	country が省略された場合に、tvmaze_get_schedule の linear および all スコープで使われる 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() のエントリーポイントです。8 つのツール、サーバーの指示、サービスのライフサイクルを登録します。
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() 配列に登録してください。
• 上流との境界処理はサービス内に保ってください。生データを検証し、ドメイン型に正規化してから、出力スキーマに沿って返します。欠落したフィールドを捏造してはいけません。放送時刻がない場合は、そのまま欠落した状態にします。

コントリビューション

Issue を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。