IMDb MCP Server

IMDb MCP サーバー

Verified on MCP Review

IMDb API サービスを使用して、映画やテレビ番組の情報を提供する Model Context Protocol（MCP）実装の Python サーバーです。

目次

• 概要
• 機能
• 要件
• 設定
• ツール
  • 検索ツール
  • IMDb ID ツール
  • 設定ツール
  • 映画ツール
  • テレビ番組ツール
  • 近日公開作品ツール
  • インドの注目作品ツール
• プロンプトと応答の例
• インストール
• サーバーの起動
• 技術詳細
  • トランスポートモード
  • ページネーションシステム
  • キャッシュシステム
• 制限事項
• トラブルシューティング
• ライセンス

概要

このサーバーは、IMDb API を通じて IMDb データにアクセスするための包括的なツールセットを提供します。エージェントと IMDb データベースをつなぐ橋渡しとして機能し、映画、テレビ番組、俳優、監督などに関する詳細情報を提供します。

機能

• 🎬 映画やテレビ番組の検索
• 📋 映画やテレビ番組に関する詳細情報
• 👨‍👩‍👧‍👦 キャストとスタッフの情報
• 🏆 高評価作品や人気作品のリスト
• 💰 興行収入データ
• 🌍 国別の映画情報（特にインド映画に注力）
• 🔜 近日公開作品
• 🔄 効率的なレスポンスキャッシュシステム

要件

• Python：3.13 以降
• パッケージマネージャー：uv（推奨）または pip
• RapidAPI アカウント：IMDb API へのアクセスに必要

設定

このサーバーで IMDb API サービスを利用するには、ご自身の RapidAPI API キーが必要です。

1. RapidAPI でアカウントを作成します
2. RapidAPI で IMDb API をサブスクライブします（無料プランも利用できます）
3. RapidAPI ダッシュボードから API キーをコピーします
4. RAPID_API_KEY_IMDB 環境変数を使ってキーを設定します。環境に応じて、次のいずれかの方法を使用してください。
   • MCP クライアントの設定 — env ブロックに設定します（インストールを参照）。通常はこちらの方法を使用します。
   • シェル：export RAPID_API_KEY_IMDB=your_api_key_here
   • .env ファイル：.env.example を .env にコピーし、uv run --env-file .env imdb-server を実行します
   • HTTP / Docker：コンテナに -e RAPID_API_KEY_IMDB=... を渡します

このキーが必要になるのは、ツールが実際に呼び出されたときだけです。キーがなくても、サーバーは起動してツールの一覧を表示します。

ツール

検索ツール

ツール	説明	例
search_imdb	さまざまな絞り込みオプションを使って映画やテレビ番組を検索します	search_imdb(primary_title="Inception")

IMDb ID ツール

ツール	説明	例
get_imdb_details	映画またはテレビ番組の詳細情報を取得します	get_imdb_details(imdb_id="tt1375666")
get_directors	映画の監督を取得します	get_directors(imdb_id="tt1375666")
get_cast	映画のキャストを取得します	get_cast(imdb_id="tt1375666")
get_writers	映画の脚本家を取得します	get_writers(imdb_id="tt1375666")

設定ツール

ツール	説明	例
get_types	利用可能なすべてのコンテンツタイプを取得します	get_types()
get_genres	利用可能なすべてのジャンルを取得します	get_genres()
get_countries	利用可能なすべての国を取得します	get_countries()
get_languages	利用可能なすべての言語を取得します	get_languages()

映画ツール

ページネーション対応（1ページあたり5件）

ツール	説明	例
get_top_250_movies	IMDbの映画トップ250を取得します	get_top_250_movies(start=0)
get_top_box_office_us	米国の興行収入記録を取得します	get_top_box_office_us(start=0)
get_most_popular_movies	最も人気のある映画を取得します	get_most_popular_movies(start=0)

テレビ番組ツール

ページネーション対応（1ページあたり5件）

ツール	説明	例
get_top_250_tv_shows	IMDbのテレビ番組トップ250を取得します	get_top_250_tv_shows(start=0)
get_most_popular_tv_shows	最も人気のあるテレビ番組を取得します	get_most_popular_tv_shows(start=0)

公開予定作品ツール

ページネーション対応（1ページあたり5件）

ツール	説明	例
get_upcoming_releases	国別に公開予定の映画やテレビ番組を取得します	get_upcoming_releases(country_code="US", type="MOVIE", start=0)
get_country_codes_for_upcoming_releases	公開予定作品で利用可能な国コードを取得します	get_country_codes_for_upcoming_releases()

インド注目作品ツール

ページネーション対応（1ページあたり5件）

ツール	説明	例
get_top_rated_malayalam_movies	評価の高いマラヤーラム語映画トップ50を取得します	get_top_rated_malayalam_movies(start=0)
get_upcoming_indian_movies	公開が最も期待されているインド映画を取得します	get_upcoming_indian_movies(start=0)
get_trending_tamil_movies	トレンドのタミル語映画を取得します	get_trending_tamil_movies(start=0)
get_trending_telugu_movies	トレンドのテルグ語映画を取得します	get_trending_telugu_movies(start=0)
get_top_rated_tamil_movies	評価の高いタミル語映画トップ50を取得します	get_top_rated_tamil_movies(start=0)
get_top_rated_telugu_movies	評価の高いテルグ語映画トップ50を取得します	get_top_rated_telugu_movies(start=0)
get_top_rated_indian_movies	評価の高いインド映画トップ250を取得します	get_top_rated_indian_movies(start=0)

プロンプトと応答の例

最も近い将来に公開されるアクション映画を5本教えてください。

公開予定のアクション映画を調べます。

MCP ツール get_upcoming_releases を呼び出しました

これらの公開予定作品からアクション映画を探します。

MCP ツール get_upcoming_releases を呼び出しました

検索結果によると、最も近い将来に公開されるアクション映画は次の5本です。

1. A Minecraft Movie（2025年4月4日）

   • ジャンル：アクション、アドベンチャー、コメディ
   • あらすじ：4人のはみ出し者がポータルを通って立方体のワンダーランドに迷い込み、熟練のクラフターと共に家に帰るための冒険に出ます。

2. Freaky Tales（2025年4月4日）

   • ジャンル：アクション、アドベンチャー、コメディ
   • あらすじ：1987年のカリフォルニア州オークランドを舞台に、音楽、映画、人々、場所、思い出への愛を描く、相互につながった4つの物語です。

3. Wake Up（2025年4月4日）

   • ジャンル：アクション、ホラー
   • あらすじ：若い活動家たちが環境問題への抗議のために家具店に侵入しますが、狩猟に夢中の夜警と共に店内に閉じ込められてしまいます。

4. Warfare（2025年4月11日）

   • ジャンル：アクション、ドラマ、戦争
   • あらすじ：元海軍特殊部隊員のレイ・メンドーサがイラク戦争中に経験した実話に基づいています。

5. The Amateur（2025年4月11日）

   • ジャンル：アクション、スリラー
   • あらすじ：CIAの暗号解読者が、妻を殺したテロリストを追うための訓練を受けさせるよう、CIAを脅迫します。

インストール

これは、独自の RapidAPI キーを使ってローカルで実行する、自己完結型の MCP サーバーです。 Smithery は無料のマネージドホスティングを提供しなくなったため、共有のリモート インスタンスはありません。サーバーをクローンする（または uvx を使う）ことで、MCP クライアントから接続してください。

オプション1：uvx で実行する（クローン不要）

uv がインストールされている場合は、MCP クライアントの 設定（例：claude_desktop_config.json）に次の内容を追加してください。

{
  "mcpServers": {
    "imdb_server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/uzaysozen/imdb-mcp-server",
        "imdb-server"
      ],
      "env": {
        "RAPID_API_KEY_IMDB": "your_api_key_here"
      }
    }
  }
}

オプション2：クローンして uv で実行する

1. uv をインストールします。

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. このリポジトリをクローンして、依存関係をインストールします。

git clone https://github.com/uzaysozen/imdb-mcp-server.git
cd imdb-mcp-server
uv sync

3. MCP クライアントの設定に次の内容を追加します。

{
  "mcpServers": {
    "imdb_server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/imdb-mcp-server",
        "run",
        "imdb-server"
      ],
      "env": {
        "RAPID_API_KEY_IMDB": "your_api_key_here"
      }
    }
  }
}

オプション3：HTTP 経由でセルフホストする（Docker）

共有の常時稼働リモートサーバーが必要な場合は、HTTP モードで実行し、独自の HTTPS エンドポイントの背後に配置してください。この方法は任意で、複数のクライアントから 1つのインスタンスに接続する場合にのみ必要です。

1. このリポジトリをクローンします。

git clone https://github.com/uzaysozen/imdb-mcp-server.git
cd imdb-mcp-server

2. Docker イメージをビルドして実行します。

docker build -t imdb_server .
docker run -d -p 8081:8081 -e RAPID_API_KEY_IMDB=your_api_key_here --name imdb_server imdb_server

コンテナはポート8081で HTTP モードで実行され、/mcp で MCP エンドポイントを提供します。 TLS を終端するリバースプロキシまたはプラットフォームの背後に配置してください。Smithery に掲載する場合は、 公開されている https://.../mcp URL を外部サーバーとして smithery.ai/new に登録してください。

サーバーの起動

Stdio モード（ローカル開発のデフォルト）

# Using uv (recommended)
uv run imdb-server

# Or directly with Python module
python -m imdb_mcp_server

HTTP モード（セルフホスト用）

# Using uv
TRANSPORT=http uv run imdb-server

# Or with Python module
TRANSPORT=http python -m imdb_mcp_server

# With custom port
TRANSPORT=http PORT=8081 uv run imdb-server

選択した設定を追加したら、MCP クライアント（例：Claude Desktop）を再起動して、IMDb サーバーを読み込んでください。これで、会話の中ですべての映画・テレビ番組データ用ツールを使えるようになります。

技術的な詳細

このサーバーは以下を基盤として構築されています。

• Python 3.13+：最新の Python ランタイム
• MCP Python SDK 2.x（mcp.server.mcpserver.MCPServer）：stdio および Streamable HTTP トランスポート
• RapidAPI 経由の IMDb API：主要なデータソース
• Requests：API 通信ライブラリ
• uv：高速な Python パッケージマネージャーおよびランナー
• カスタムのインメモリーキャッシュシステム：LRU 方式の削除による最適化されたレスポンスキャッシュ
• スマートなページネーション：AI エージェントでの利用に最適化するため、リクエストごとの結果を5件に制限します

トランスポートモード

サーバーは、TRANSPORT 環境変数で選択する2つのトランスポートモードをサポートしています。

1. Stdio モード（TRANSPORT が未設定の場合 — デフォルト）：標準入力／出力を介した MCP 通信

   • ローカルの MCP クライアント（Claude Desktop、Claude Code、Cursor など）で使用します
   • API キーは RAPID_API_KEY_IMDB 環境変数から取得します

2. HTTP モード（TRANSPORT=http）：Streamable HTTP トランスポート

   • 共有インスタンスをセルフホストする場合に使用します（Docker、またはコンテナを実行する任意のプラットフォーム）
   • /mcp で MCP エンドポイントを提供します
   • シングルテナントです。API キーはサーバー上の RAPID_API_KEY_IMDB から取得します
   • デフォルトで 0.0.0.0:8081 にバインドします（HOST／PORT 環境変数）。TLS を終端するプロキシの背後で実行してください

ページネーションシステム

すべてのデータ取得ツールは、AI エージェントのパフォーマンスを高めるためにページネーションを実装しています。

目的

• AI に最適化された応答：各応答を5件に制限し、データを処理する AI エージェントが過負荷にならないようにします
• 焦点を絞った結果：エージェントがユーザーに、より関連性が高く簡潔な情報を提供できるようにします
• 処理の改善：映画やテレビ番組のデータを分析する際、AI エージェントの認知負荷を軽減します

実装

• ページネーションに対応する各エンドポイントは、start パラメーターを受け取ります（デフォルト：0）
• 結果にはナビゲーション用のメタデータ（totalCount、hasMore、nextStart）が含まれます
• すべてのコレクションエンドポイントで、ページサイズを一律5件にしています
• ページネーションを使ったリクエストの例：get_top_250_movies(start=5) は6～10件目を返します

メリット

• エージェントの応答品質向上：AI エージェントが一度に大量のデータを受け取らないようにします
• 扱いやすい情報：エージェントが効果的に処理できる、消化しやすいデータのまとまりを作ります
• 順次アクセス：複数回のツール呼び出しを通じて、大規模なデータセットを体系的に探索できます

キャッシュシステム

サーバーは、パフォーマンスを高め、API 呼び出しを減らすために、効率的なキャッシュシステムを実装しています。

機能

• インメモリーキャッシュ：API 応答をメモリーに保存し、すばやく取得できます
• 有効期限とサイズの設定：キャッシュ項目は設定可能な期間（デフォルト：10分）が経過すると有効期限が切れます。デフォルトのキャッシュキー数は100です
• キャッシュの自動クリーンアップ：バックグラウンドスレッドを使用し、定期的に（デフォルト：5分）期限切れの項目を削除してメモリー使用量を管理します
• キャッシュキー：一意性を確保するため、URL とクエリパラメーターに基づいて生成されます

メリット

• API 使用量の削減：応答を再利用し、API のレート制限内に収まりやすくします
• 応答時間の短縮：キャッシュされたクエリでは、ネットワーク遅延がなくなります
• コスト効率：特に人気の高いクエリや繰り返し実行されるクエリで、API 呼び出しの数を最小限に抑えます

設定

キャッシュサイズと有効期限は、src/imdb_mcp_server/cache.py で調整できます。

# Defaults: 600 seconds (10 minutes) and 100 cache keys
# You can customize by modifying the ResponseCache instantiation:
response_cache = ResponseCache(max_size=100, expiry_seconds=600)

# Example with custom values:
# response_cache = ResponseCache(max_size=50, expiry_seconds=120)

制限事項

• API のレート制限は、RapidAPI のサブスクリプションに応じて適用されます
• 詳細情報の取得には、追加の API 呼び出しが必要になる場合があります
• 検索結果は、1回のリクエストで取得できる件数に上限がある場合があります
• サーバーを再起動すると、インメモリーキャッシュは失われます
• ページネーションを使用する応答は、1ページあたり最大5件を返します

トラブルシューティング

問題	解決方法
API キーが認識されない	RAPID_API_KEY_IMDB が設定されていることを確認してください。MCP クライアントの設定の env ブロック、シェル、.env、または Docker コンテナの -e で設定できます
ModuleNotFoundError: No module named 'mcp.server.fastmcp'	mcp 2.x がインストールされた古いチェックアウトを使用しています。最新の内容を取得し（このサーバーは mcp 2.x / MCPServer を対象としています）、uv sync を実行してください
IMDb API からの HTTP 401 / HTTP 403	RapidAPI キーが無効か、IMDb API に登録されていません。RapidAPI でIMDb APIに登録（または再登録）し、新しいキーをコピーしてください
IMDb API からの HTTP 404	RapidAPI の登録が無効になっているか、上流のエンドポイントが変更されています。RapidAPI ダッシュボードで登録状況を確認してください
古い npx @smithery/cli install コマンドが失敗する	Smithery は無料のマネージドホスティングを終了したため（2026 年 3 月）、共有リモートインスタンスはありません。代わりにローカルにインストールしてください。インストールを参照してください
レート制限を超過した	RapidAPI ダッシュボードで RapidAPI の登録プランと制限を確認してください
タイムアウトエラー	サーバーのタイムアウトは 30 秒です。大規模なリクエストの場合は、パラメーターを制限するか、ページネーションを使用してください
結果が空	より広範な検索語を試すか、コンテンツが IMDb のデータベースに存在するか確認してください
メモリ使用量が多い	一意のクエリを多数処理しながら長時間実行する場合は、キャッシュをクリアするため、ときどきサーバーを再起動してください
ポートがすでに使用されている	PORT 環境変数を使用してポートを変更してください（HTTP モードのみ）：TRANSPORT=http PORT=8082 uv run imdb-server
インポートエラー	すべての依存関係がインストールされていることを確認してください：uv sync（または pip install "mcp[cli]>=2.1,<3" requests）
接続が拒否される（Docker）	コンテナが実行中であることを確認してください：docker ps。また、ログを確認してください：docker logs imdb_server

ライセンス

この MCP サーバーは MIT ライセンスの下で利用できます。