TMDB MCP Server

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

ツール

映画の発見

• get_weekend_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による詳細な経歴 + フィルモグラフィー（映画 + テレビ）

リソース

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

Related MCP server: Usher MCP

クイックスタート

1. themoviedb.orgでTMDB APIキーを取得 → アカウント設定 → API

2. クローン、インストール、ビルド:

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

3. ローカルのenvファイルを作成し、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 を呼び出します。

ローカル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 を省略してください。

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」も提供します。気分、国、言語、上映時間、評価、ストリーミングサービスを尋ね、TMDBの発見、トレンド、上映中、クレジット、ポスター、視聴プロバイダーデータを使用して、ランク付けされた映画のショートリストを作成します。

ブラウザデモには、デプロイされた /mcp ルートを呼び出し、期待されるツール契約を検証し、compare_movies、find_where_to_watch、get_weekend_watchlist をサンプリングする MCPツール表面 パネルも含まれています。

完全なブラウザアプリ、デプロイされた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 (ランク付けされた映画の選択用)

• GET /health (デプロイの健全性確認用)

• POST /mcp (リモート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: 優先ストリーミングサービス

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サーバーとして登録

• プラグインUIに表示されるようにローカルの TMDB プラグインペイロードをインストール

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