TMDB MCP Server

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

ツール

映画の検索・発見

• get_weekend_watchlist — 気分、国、言語、上映時間、評価、配信サービスに基づいた週末のおすすめリスト

• search_movies — タイトル/キーワードで検索 → タイトル、ID、評価、概要を取得

• get_trending — トレンド映画トップ10 (timeWindow: "day" | "week")

• search_by_genre — ジャンル名による映画検索（年フィルターオプションあり）

• advanced_search — ジャンル、年、最低評価、並び替え、言語によるフィルタリング

• search_by_keyword — テーマ/キーワード（例: "zombie", "heist"）で映画を検索

映画の詳細

• get_movie_details — 詳細情報: キャスト、スタッフ、上映時間、ジャンル、レビュー (movieIdで指定)

• get_recommendations — 映画IDに基づいたおすすめトップ5

• get_similar_movies — TMDBの類似性アルゴリズムによる類似映画

• get_watch_providers — 国別のストリーミング/レンタル/購入状況 (デフォルト: IN)

テレビ番組

• 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: TMDB MCP Server

クイックスタート

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__ 名前空間が公開されるはずです。

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の発見、トレンド、上映中、クレジット、ポスター、配信プロバイダーデータを使用して、ランク付けされた映画のショートリストを作成します。

完全なブラウザアプリ、デプロイされた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

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: 好みのストリーミングサービス

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