TMDB MCP Server

TMDB MCP サーバー

The Movie Database（TMDB）API 用の MCP サーバーです。Codex や Claude Desktop などのアシスタント向けに、映画やテレビ番組の検索、配信状況、キャストとスタッフの詳細、おすすめ情報を提供します。

再利用可能な MCP サーバーと、より上位の機能ワークフローを分けるアーキテクチャについては、USERGUIDE.md をご覧ください。

ツール

映画を探す

• get_weekend_watchlist — 気分、国、言語、上映時間、評価、配信サービスに基づいて週末に観る作品をランキング形式で絞り込み
• plan_watch_party — メイン作品、予備作品、意外な選択肢、パーティー向けの理由、配信状況、除外タイトルのフィルタリングを含む、グループでの映画鑑賞プラン
• build_franchise_watch_order — 公開順、おすすめの順番、合計上映時間、配信サービスに応じた注記を含む、フランチャイズ／ユニバースのガイド
• build_collection_gap_plan — 視聴済み／未視聴の作品、残りの上映時間、配信状況、完了までの手順を含む、フランチャイズ完走プラン
• recommend_from_taste_profile — 好きな作品と嫌いな作品に基づくおすすめ。配信サービスに応じたスコア、相性の理由、注意点を含みます
• build_release_calendar_watchlist — 公開時期に基づく視聴リスト。今後公開される映画、すぐに視聴できる作品、幅広い層向けの候補、後で観る作品のスコアを含みます
• search_movies — タイトル／キーワードで検索 → タイトル、ID、評価、概要
• get_trending — 人気上位10作品（timeWindow: "day" | "week"）
• get_weekly_trending_by_language — 週間の人気映画を原語別に英語、ヒンディー語、テルグ語に分類
• search_by_genre — ジャンル名で映画を検索。年による絞り込みも可能
• advanced_search — ジャンル、年、最低評価、並べ替え、言語で絞り込み
• search_by_keyword — テーマ／キーワード（例：「zombie」、「heist」）で映画を検索

映画の詳細

• get_movie_details — キャスト、スタッフ、上映時間、ジャンル、レビューを含む詳細情報（movieId で指定）
• compare_movies — 評価、上映時間、キャスト、監督、配信サービス、最適な候補についての注記を含む、2～5件の映画IDの比較
• get_recommendations — 映画IDに基づくおすすめ上位5件
• get_similar_movies — TMDB の類似度アルゴリズムによる類似映画
• get_watch_providers — 国別のストリーミング／レンタル／購入状況（デフォルト：IN）
• find_where_to_watch — 映画タイトルを1～5件検索し、希望するサービスとの一致情報を含むストリーミング／レンタル／購入状況を返します

テレビ番組

• search_tv_shows — タイトルでテレビシリーズを検索
• get_trending_tv — 人気上位10番組（timeWindow: "day" | "week"）

人物

• search_person — 名前で俳優、監督、スタッフを検索 → ID と主な出演作・作品
• get_person_details — personId で指定した人物の詳しいプロフィールと出演作品（映画＋テレビ）
• build_person_watch_path — 評価の高い作品、現在視聴可能な作品、最近の作品、入門におすすめの作品を含む、俳優／監督の視聴ガイド

リソース

• tmdb:///movie/<id> — 映画の詳細情報を JSON で提供（タイトル、キャスト、監督、レビュー、ポスター URL）

クイックスタート

1. themoviedb.org → Account Settings → API で TMDB API キーを取得します

2. クローンして、インストールし、ビルドします：

   git clone https://github.com/Laksh-star/mcp-server-tmdb.git
   cd mcp-server-tmdb
   npm install
   

3. ローカルの環境ファイルを作成し、TMDB キーを追加します：

   cp .env.example .env
   

4. ローカルの Codex と Claude Desktop の連携機能をインストールします：

   npm run install:local
   

5. Codex または Claude Desktop をすでに開いている場合は、再起動します。

6. 次のようなプロンプトで動作を確認します：

   What movies are trending this week?
   

Codex では、新しいセッションを開始すると、プラグイン一覧に TMDB が表示され、mcp__tmdb__ 名前空間が利用できるはずです。

ツールサーフェスのスモークテスト

ツールの追加またはマージ後に、このスモークテストを実行します。想定される MCP ツールの契約を検証し、主要なワークフローツールである compare_movies、find_where_to_watch、get_weekend_watchlist、plan_watch_party、build_franchise_watch_order、build_collection_gap_plan、recommend_from_taste_profile、build_person_watch_path を呼び出します。

ローカル stdio MCP：

npm run build
set -a && source ./.env && set +a && npm run smoke:tools

Cloudflare ホスト型 MCP：

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/tool-surface-smoke.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp

スクリプトは、簡潔な検証用成果物を次の場所に書き込みます。

examples/tool-surface-smoke.md

ツールの肥大化を避けるには、複数の TMDB 呼び出しを組み合わせて、ユーザーにとって有用な判断につなげるワークフローツールの追加を優先してください。生のエンドポイント形式のツールは、幅広く再利用できるプリミティブである場合に限り維持します。

週間トレンド言語デモ

このリポジトリには、MCP ツール get_weekly_trending_by_language を呼び出す、小規模で共有可能なデモが含まれています。このツールは、TMDB の週間トレンド映画データをリアルタイムで取得し、TMDB の original_language に基づいて現在の最初のページをグループ化します。

ローカル stdio MCP サーバーに対して実行します。

npm run build
set -a && source ./.env && set +a && npm run demo:weekly-trending

このバージョンの Worker をデプロイした後、同じデモをリモート MCP エンドポイントに対して実行します。

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/weekly-trending-languages.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp

個人でのテスト用に、意図的に認証なしでデプロイしている場合は、TMDB_MCP_ACCESS_TOKEN を省略します。

週間ストリーミングレーダー

このリポジトリには、スクリプト主体の週間レーダーも含まれています。既存の MCP ツールを連鎖させて、映画のトレンド、テレビ番組のトレンド、言語の勢い、すぐに選べる作品、家族向けの作品、好みのプロファイルを使った調査をまとめた Markdown 成果物を作成します。

ローカル stdio MCP：

npm run build
set -a && source ./.env && set +a && npm run demo:weekly-radar -- --country US

Cloudflare ホスト型 MCP：

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/weekly-streaming-radar.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --country US

スクリプトは次のファイルを書き込みます。

examples/weekly-streaming-radar.md

公開カレンダーのウォッチリスト

公開カレンダーは、MCP ツール build_release_calendar_watchlist として利用できます。デモスクリプトはこのツールを呼び出し、公開時期の確認、後で観る候補、配信プロバイダーですぐに視聴できる作品、幅広い視聴者向けの基準作品をまとめた Markdown 成果物を書き込みます。

ローカル stdio MCP：

npm run build
set -a && source ./.env && set +a && npm run demo:release-calendar -- --country US --days 90

Cloudflare ホスト型 MCP：

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/release-calendar-watchlist.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --country US --days 90

スクリプトは次のファイルを書き込みます。

examples/release-calendar-watchlist.md

プロバイダー変更モニター

プロバイダーモニターは、状態を保持する必要があるため、スクリプト主体になっています。find_where_to_watch を呼び出し、現在のプロバイダー一覧を JSON スナップショットと比較して、新規、削除、変更なし、利用可能なプロバイダー情報なしの項目を示す Markdown の差分レポートを書き込みます。

ローカル stdio MCP：

npm run build
set -a && source ./.env && set +a && npm run demo:provider-monitor -- --country US --titles "The Matrix,Inception" --services "Netflix,Prime Video"

Cloudflare ホスト型 MCP：

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/provider-change-monitor.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --country US --titles "The Matrix,Inception" --services "Netflix,Prime Video"

スクリプトは次のファイルを書き込みます。

examples/provider-change-monitor.md
examples/provider-change-snapshot.json

コレクションの未視聴作品検索

コレクションの未視聴作品検索スクリプトは、昇格された MCP ツール build_collection_gap_plan を呼び出すようになりました。視聴済みの作品、未視聴の作品、残りの再生時間、プロバイダーの利用可否、最短の視聴完了ルートをまとめた、繰り返し利用できる Markdown の完了レポートを書き込みます。

ローカル stdio MCP：

npm run build
set -a && source ./.env && set +a && npm run demo:collection-gaps -- --franchise "The Matrix" --watched "The Matrix" --country US --services "Netflix,Prime Video"

Cloudflare ホスト型 MCP：

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/collection-gap-finder.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --franchise "The Matrix" --watched "The Matrix" --country US --services "Netflix,Prime Video"

スクリプトは次のファイルを書き込みます。

examples/collection-gap-finder.md

Cloudflare Workers 上のリモート MCP

このリポジトリは、Cloudflare Workers 上でリモート MCP サーバーとしても実行できます。リモートサーバーは、Streamable HTTP 経由で /mcp に同じ TMDB ツールを公開するため、Claude、Cowork、Claude Desktop コネクター、その他のリモート MCP クライアントは公開 URL に接続できます。

既存のローカル stdio サーバーは、Codex とローカルの Claude Desktop での使用に変更ありません。Cloudflare のエントリーポイントは src/worker.ts です。

Worker は、ブラウザデモも / で提供します。Weekend Watch Concierge は、1人での作品選びと Watch Party モードに対応し、TMDB のディスカバリー、トレンド、上映中の作品、クレジット、ポスター、配信プロバイダーのデータを使って、ランク付けされた映画の候補リストを作成します。ブラウザアプリには、Cloudflare の使い方を説明するヘルプドロワーと、Weekly Streaming Radar、Provider Change Monitor、Collection Gap Finder などのスクリプト優先アーティファクト用コマンドを表示する Workflow Demos パネルもあります。

ブラウザデモには、デプロイ済みの /mcp ルートを呼び出し、期待されるツールの契約を検証して、compare_movies、find_where_to_watch、get_weekend_watchlist、plan_watch_party、build_franchise_watch_order、build_collection_gap_plan、recommend_from_taste_profile、build_person_watch_path を試す MCP tool surface パネルもあります。

ブラウザアプリ、デプロイ済み Worker、アクセストークン、MCP の引き継ぎについては、docs/weekend-watch-concierge.md をご覧ください。

デプロイ

1. Cloudflare にログインします。

   npx wrangler login
   

2. TMDB キーを Worker シークレットとして保存します。

   npx wrangler secret put TMDB_API_KEY
   

3. デプロイを共有する前に、アクセストークンを Worker シークレットとして保存します。

   npx wrangler secret put ACCESS_TOKEN
   

   ACCESS_TOKEN が設定されている場合、POST /api/concierge と POST /mcp には次のものが必要です。

   Authorization: Bearer <your-access-token>
   

4. Worker バンドルを確認します。

   npm run worker:dry-run
   

5. デプロイします。

   npm run worker:deploy
   

Cloudflare から次のような URL が表示されます。

https://tmdb-mcp.<your-workers-subdomain>.workers.dev

リモートクライアントでは、この MCP エンドポイントを使用します。

https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp

ブラウザデモの URL は次のとおりです。

https://tmdb-mcp.<your-workers-subdomain>.workers.dev/

Claude / Cowork から接続する

Claude のカスタムコネクターを設定するには、次の手順に従います。

1. Claude の設定を開きます。Customize -> Connectors の順に選択します。
2. + -> Add custom connector をクリックします。
3. デプロイ済みの Worker MCP URL を使用します。

   https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp
   

4. 会話でコネクターを有効にし、次のような TMDB に関する質問をします。

   What movies are trending this week?
   

ローカルコマンドが引き続き必要な Claude Desktop のバージョンや MCP クライアントでは、mcp-remote プロキシを使用します。

{
  "mcpServers": {
    "tmdb-remote": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp"
      ]
    }
  }
}

セキュリティに関する注意

ACCESS_TOKEN が設定されていない場合、個人でのテストを簡単にするため、Worker は認証なしで利用できます。Worker の URL を知っている人なら誰でも読み取り専用の TMDB ツールを呼び出し、TMDB API の利用枠を消費できます。自分のアカウント以外と共有する前に、ACCESS_TOKEN を設定するか、Cloudflare Access を使用してください。

Weekend Watch Concierge

オフラインコンシェルジュのテストを実行します。

npm test

TypeScript プロジェクトをビルドし、小規模なローカル TMDB 互換フィクスチャサーバーを起動して、createWeekendConcierge が実行時フィルターに従いながら、指定されたストリーミングサービスに合致する作品を最初にランク付けすることを検証します。TMDB API キーは不要です。

Worker をローカルで実行します。

npm run worker:dev

.env のローカル値を追跡対象外の .dev.vars ファイルに同期し、ローカル開発中に Wrangler が TMDB_API_KEY を Worker に公開できるようにします。

保護されたローカルテストを行うには、.env に ACCESS_TOKEN を追加します。ブラウザーアプリにはアクセストークン欄があり、スモークテスト用スクリプトはシェル環境から ACCESS_TOKEN または TMDB_MCP_ACCESS_TOKEN を読み取れます。

次を開きます。

http://127.0.0.1:8787/

ローカル Worker の起動後、コンシェルジュ API のスモークテストを実行します。

npm run smoke:concierge

リモート MCP エンドポイントのスモークテストを実行し、エージェント向けコンシェルジュツールを呼び出します。

node scripts/remote-mcp-smoke.mjs http://127.0.0.1:8787/mcp --call-concierge

保護されたデプロイの場合：

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/remote-mcp-smoke.mjs https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --call-concierge

または、デプロイ済みの Worker をテストします。

node scripts/concierge-smoke.mjs https://tmdb-mcp.<your-workers-subdomain>.workers.dev

アプリは次を使用します。

• ランク付けされた映画の候補には POST /api/concierge
• Planning Lab のコレクションの見逃しには POST /api/collection-gap-plan
• Planning Lab の好みに合ったおすすめには POST /api/taste-profile
• Planning Lab の人物別視聴順には POST /api/person-watch-path
• デプロイのヘルスチェックには GET /health
• リモート MCP クライアントには POST /mcp

エージェントは get_weekend_watchlist を次の値で呼び出せます。

• mood：crowd、thriller、thoughtful、funny、family、mindbend のいずれか
• country：視聴プロバイダーの地域。例：IN または US
• language：オリジナル言語のコード。例：en、hi、ta、te、any
• runtime：最大再生時間（分）。例：120、150、any
• minRating：TMDB の最低評価
• services：優先するストリーミングサービス
• familySafe：true に設定すると、TMDB のジャンルデータが利用可能な場合に一般的な成人向けジャンルを除外します

エージェントは、グループで視聴する作品を決める際に plan_watch_party を呼び出せます。次の値を受け取ります。

• moods：crowd、thriller、thoughtful、funny、family、mindbend のいずれか1～3個
• groupSize：視聴する人数
• country、language、runtime、minRating、services：週末のウォッチリストと同じ意味
• avoidTitles：グループがすでに視聴したタイトル、または除外したいタイトル
• familySafe：true に設定すると、TMDB のジャンルデータが利用可能な場合に一般的な成人向けジャンルを除外します

エージェントは、コレクションまたはユニバースのガイドとして build_franchise_watch_order を呼び出せます。次の値を受け取ります。

• query：フランチャイズまたはコレクション名。例：The Matrix、Dune、Batman、Mission Impossible
• country：視聴プロバイダーの地域。例：IN または US
• maxMovies：含めるコレクション項目の最大数。2～20

エージェントは、フランチャイズの見終わっていない作品を計画するために build_collection_gap_plan を呼び出せます。次の値を受け取ります。

• query：フランチャイズまたはコレクション名
• watchedTitles：視聴済みタイトルまたは TMDB 映画 ID
• country：視聴プロバイダーの地域。例：IN または US
• services：優先するストリーミングサービス
• maxMovies：含めるコレクション項目の最大数。2～20

エージェントは、パーソナライズされたおすすめを得るために recommend_from_taste_profile を呼び出せます。次の値を受け取ります。

• likedTitles：ユーザーが気に入っている映画を1～5本
• dislikedTitles：ユーザーが好まない、または作風として避けたい映画（任意）
• country、services、language、runtime、minRating：フィルターと今すぐ視聴する際の希望
• maxResults：返すおすすめの数。3～10

エージェントは、俳優、監督、脚本家、またはスタッフの人物別に build_person_watch_path を呼び出せます。次の値を受け取ります。

• name：人物名。例：Keanu Reeves または Christopher Nolan
• country：視聴プロバイダーの地域。例：IN または US
• services：優先するストリーミングサービス
• maxTitles：視聴順に含めるタイトルの数。3～8

Cloudflare MCP デモワークフロー

エンドツーエンドのエージェントワークフローを具体的に確認するには、現在上映中の作品を扱う後続デモを実行してください。リモートクライアントと同じように、MCP サーバーを使用します。

1. 選択した地域で現在上映中の作品を探すための get_now_playing
2. 選択した作品の詳細を取得するための get_movie_details
3. 現在視聴可能かどうかを確認するための get_watch_providers
4. get_recommendations。非常に新しい作品の場合は get_similar_movies にフォールバックします
5. 後続の視聴可能状況を確認するための get_watch_providers

ローカルの stdio MCP：

npm run build
set -a && source ./.env && set +a && npm run demo:now-playing -- --region US

Cloudflare ホスト型 MCP：

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/now-playing-follow-on-demo.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --region US

スクリプトは最終成果物を次の場所に書き込みます。

examples/now-playing-follow-on-demo.md

npm run install:local の動作

インストーラーは、リポジトリが管理するランチャー plugins/tmdb/scripts/run-server.sh を使用します。

Codex の場合、次の処理を行います。

• ランチャーを MCP サーバーとして登録します
• ローカルの TMDB プラグインペイロードをインストールし、プラグイン UI に表示します

Claude Desktop の場合、次の処理を行います。

• 同じランチャーをローカル MCP サーバーとして登録します

次のファイルを更新します。

• ~/.codex/config.toml
• ~/.codex/.tmp/plugins/.agents/plugins/marketplace.json
• ~/.codex/plugins/cache/openai-curated/tmdb/...
• ~/Library/Application Support/Claude/claude_desktop_config.json

ランチャーは、シェル環境またはリポジトリの .env ファイルから TMDB_API_KEY を読み込みます。

Claude Desktop での使用方法

手動で設定する場合は、~/Library/Application Support/Claude/claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "tmdb-local": {
      "command": "/full/path/to/mcp-server-tmdb/plugins/tmdb/scripts/run-server.sh",
      "args": []
    }
  }
}

設定を編集した後、Claude Desktop を再起動してください。

Codex での使用方法

インストーラーは、~/.codex/config.toml に次のブロックを追加します。

[mcp_servers.tmdb_local]
command = "/full/path/to/mcp-server-tmdb/plugins/tmdb/scripts/run-server.sh"

[plugins."tmdb@openai-curated"]
enabled = true

設定を編集した後、Codex を再起動してください。新しい Codex セッションでは、プラグイン一覧に TMDB が表示され、mcp__tmdb__ 名前空間が追加されます。

検証

オフラインのスモークテスト：

TMDB_API_KEY=dummy node plugins/tmdb/scripts/smoke-test.mjs

オンラインのスモークテスト：

set -a && source ./.env && set +a && node plugins/tmdb/scripts/smoke-test.mjs --online

プラグインのドキュメント

プラグインのパッケージ化、ローカルインストールの動作、Codex 固有の注意事項については、plugins/tmdb/README.md を参照してください。

BizClaw / NanoClaw での使用方法

エージェントコンテナに組み込まれています。.env ファイルに TMDB_API_KEY を設定するだけで使用でき、設定は不要です。

プロンプトの例

"What's trending in movies this week?"
"Find me Thriller movies from 2023"
"Who is Christopher Nolan and what has he directed?"
"Where can I watch Inception in India?"
"Get details for movie ID 550 (Fight Club)"
"Find movies similar to Interstellar"
"What are the trending TV shows right now?"

ライセンス

MIT