tmdb-mcp-server

---

概要

The Movie Database（TMDB）が提供する映画・テレビ番組のメタデータを利用できます。名前からタイトルや人物を検索し、クレジットや出演作品の一覧を取得できます。条件を絞ってタイトルを探したり、トレンドのコンテンツを確認したり、お住まいの地域での配信状況を調べたりできます。

ツール

ツール	説明
tmdb_search_titles	名前から映画、テレビ番組、人物を検索します。必須の最初のステップです。名前を詳細取得ツールが利用する整数IDに変換します。
tmdb_get_movie	1回の呼び出しで映画の詳細をすべて取得します。あらすじ、上映時間、ジャンル、米国のレーティング、予算・収益、キャスト、スタッフ、予告編、おすすめ、キーワード、外部IDを取得できます。
tmdb_get_show	テレビ番組の詳細をすべて取得します。概要、放送日、配信状況、シーズン数・エピソード数、制作陣、ネットワーク、シーズンの概要、キャスト、予告編、コンテンツレーティングを確認できます。
tmdb_get_season	1シーズン分のエピソード一覧を取得します。各エピソードのタイトル、放送日、上映時間、投票平均、スチル画像、ゲストスターに加え、そのシーズンのレギュラーキャストも取得できます。
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件の出演クレジットと50件のスタッフクレジット、および全件数を含む人物の詳細です。続きのページを取得するにはtmdb_get_personを使用してください。

機能リファレンス

tmdb_search_titles _ツール

• multiモード（デフォルト）では映画、番組、人物を混在させ、media_typeで種類を示します。movie、tv、personを指定すると、1種類に限定できます
• year（映画／テレビモード）、language、include_adult、pageは任意です。結果が空の場合も通常どおり応答し、復旧方法を案内します
• 各結果には、id、media_type、タイトル／名前、release_year、overview、vote_average、genre_names、ポスターまたはプロフィールのURLが含まれます

---

tmdb_get_movie _ツール

• クレジット、動画、おすすめ、類似作品、キーワード、外部ID、公開日を1回の呼び出しで返します。ペイロードを小さくするには、append配列を（例：["credits"]のように）絞り込んでください
• 米国のレーティング、主要キャスト、主要スタッフ、視聴URL付きのYouTube予告編が含まれます
• ストリーミング配信状況は含まれません。tmdb_get_watch_providersを使用してください

---

tmdb_get_show _ツール

• tmdb_get_movieと同じappendオプションを使用しますが、release_datesの代わりにcontent_ratings（米国のテレビ番組レーティング）を指定できます
• シーズン概要、制作陣、ネットワーク、直近に放送された／次に放送されるエピソードが追加されます
• エピソードを取得するには、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（デフォルト）、または1種類に限定
• time_window：dayまたはweek（デフォルト）
• 1ページにつき最大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 固有の機能：

• v4 Read Access Token で認証する、TMDB v3 REST API 用の型付きクライアント
• 画像パスを完全な画像 URL に解決します。パスがない場合、そのフィールドは省略されます
• ジャンル ID をジャンル名に解決するため、リストの結果を追加の呼び出しなしで読み取れます
• 詳細ツールは、クレジット、動画、おすすめ、キーワード、外部 ID を 1 回のリクエストで返します
• JustWatch を利用した地域対応のストリーミング配信状況。地域は常に明示的な入力として指定します

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

• すべての応答の enrichment.attribution に TMDB の帰属情報を含めます
• リスト応答には、総件数、ページ／総ページ数、および実際に適用されたフィルターの通知が含まれます
• 結果が空の場合は、エラーではなく復旧のための案内とともに正常に返されます
• 配信プロバイダーの結果には常に地域が示されます。件数に上限のある作品一覧では、全件数が明示されます

はじめに

TMDB API Read Access Token が必要です。無料の TMDB アカウントを作成し、API 設定から API Read Access Token（v4 JWT）をコピーしてください。このサーバーは v3 エンドポイントの認証に Authorization: Bearer <token> を使用します。従来の ?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）です。8 つの 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 のバレル経由で登録します

クレジット

この製品は TMDB API を使用していますが、TMDB による推奨または認証を受けたものではありません。ストリーミング配信状況のデータは、TMDB を通じて JustWatch から提供されており、地域によって異なります。

貢献

問題の報告を歓迎します。提出する前に、チェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

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