mcpField
T
tmdb

tmdb

github.com/magnus919その他15355 回インストール今日更新
リポジトリ

tmdb について

tmdbは、TMDbの映画・テレビ番組メタデータをコマンドラインで読み取り専用で調べるスキルです。検索やID照合、詳細取得、トレンドやおすすめの絞り込みに対応します。

主な機能

  1. 01映画・テレビ番組の検索
  2. 02外部IDによる照合
  3. 03詳細とクレジットの取得
  4. 04条件による作品の検索
  5. 05トレンド、ジャンル、認証区分の閲覧

活用シーン

  1. 01IMDb IDから映画を特定
  2. 02作品のクレジットや動画を取得
  3. 03評価と日付でホラー作品を絞り込む
  4. 04トレンド作品や認証区分を確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/magnus919/agent-skills --skill tmdb

インストール後、Claude Code で/tmdbを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

README.md
evals/
evals.json
references/
auth-pagination-and-errors.md
find-and-details.md
search-discover-trending.md
scripts/
test_tmdb.py
tmdb

詳細

ターミナルからTMDbのメタデータを取得

セットアップ

TMDb API settingsで認証情報を作成します。API Read Access Tokenの使用をおすすめします。

export TMDB_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
# Or use the v3 key: export TMDB_API_KEY="YOUR_API_KEY"

CLIはAuthorization: Bearer $TMDB_ACCESS_TOKENまたは?api_key=$TMDB_API_KEYを送信します。どちらの形式でもv3のアクセスレベルは同じです。設定するのは一方だけにしてください。--helpと--dry-runには認証情報は必要ありません。

基本コマンド

検索と識別
tmdb movie search --term "dune" --limit 5 --json
tmdb tv search --term "severance" --limit 5
tmdb find tt0111161 --source imdb_id --json

--sourceには、公式の外部ソース値のいずれかを指定します：imdb_id、facebook_id、instagram_id、tvdb_id、tiktok_id、twitter_id、wikidata_id、youtube_id。Freebaseの検索には対応していません。廃止されたfreebase_midとfreebase_idの値は拒否されます。レスポンスはmovie_results、tv_results、person_results、tv_season_results、tv_episode_resultsに分かれます。

詳細情報と補足データ
tmdb movie detail 550 --append credits,videos --json
tmdb movie detail 550 --append 'credits,watch/providers,external_ids' --json

複合レスポンスでは、リクエストした名前がトップレベルのキーとして使用されます。生のURLを構築する場合は、watch/providers内のスラッシュをエンコードしてください。

検索と閲覧
tmdb movie discover --genre horror --rating 7 --limit 10
tmdb movie discover --genre horror --certification R --from 2024-01-01 --to 2024-12-31
tmdb trending --type all --window week --limit 20 --json
tmdb genre list --type movie --json
tmdb genre list --type tv --json
tmdb certification --json

生のdiscoverリクエストでは、投票数が非常に少ない作品が上位に表示されないよう、vote_average.descとともにvote_count.gteを使用してください。現在のTMDbドキュメントでは、カンマ区切りのジャンルIDはAND、パイプ区切りのIDはORとして扱われます。

パイプラインのレシピ

IMDb IDから映画情報を補完
  1. IMDb識別子を解決します。
curl -s -H "Authorization: Bearer $TMDB_ACCESS_TOKEN" \
  'https://api.themoviedb.org/3/find/tt0111161?external_source=imdb_id' > /tmp/find.json
id=$(jq -r '.movie_results[0].id' /tmp/find.json)
  1. 詳細情報と複合リソースを取得します。
curl -s -H "Authorization: Bearer $TMDB_ACCESS_TOKEN" \
  "https://api.themoviedb.org/3/movie/$id?append_to_response=credits,videos,watch%2Fproviders" \
  | jq '{title, runtime, director: [.credits.crew[] | select(.job == "Director") | .name], cast: [.credits.cast[0:5][].name], providers: .["watch/providers"].results.US}'
検索してから詳細を取得
tmdb movie search --term "dune" --limit 1 --json > /tmp/search.json
id=$(jq -r '.results[0].id' /tmp/search.json)
tmdb movie detail "$id" --append recommendations,similar --json
信頼性の高い検索結果に絞り込む

APIを直接使う場合は、日付範囲、パイプ区切りのORまたはカンマ区切りのANDによるジャンル指定、vote_count.gte、sort_by=vote_average.descを組み合わせます。その後、次のワークフローの手順に必要なフィールドだけをjqで抽出します。

JSONとjq

--jsonはサブコマンドの前後どちらに置いてもかまいません。JSON形式の検索結果にはresultsと、通常はpage、total_pages、total_resultsのページネーションフィールドが含まれます。サービスで指定できるページ番号は500までです。安定した表形式で受け渡すには、jq -r '.results[] | [.id, (.title // .name)] | @tsv'を使用します。

既知の注意点

  • 認証情報の使い分け： api_keyとBearerは代替の認証方式であり、混在させるものではありません。認証情報が拒否されると、通常はHTTP 401、status_code: 7、Invalid API key: You must be granted a valid key.が返されます。権限エラーのコードは3です。コード33は無効なリクエストトークンを示し、このAPIキーのメッセージとは異なります。
  • ページネーションの上限： ページ番号は1から始まり、最大500です。上限を超えるリクエストは失敗します。検索とdiscoverでアクセスできる結果は、合計数がそれ以上に見える場合でも、実質10,000件までです。レートの目安は毎秒約40リクエストです。429レスポンスが返された場合はRetry-Afterに従ってください。
  • 複合リクエストの構文： appendの値はカンマ区切りで、呼び出しは最大20件です。watch/providersにはスラッシュが含まれるため、curlではURLエンコードし、jqでは.\"watch/providers\"の記法を使用してください。
  • 外部IDのレスポンス形式： /find/は汎用のidを返しません。映画またはTVの詳細を選ぶ前に、該当するネストされた配列を確認してください。有効なのは、ドキュメントに記載された8つのexternal_source値だけです。廃止されたFreebaseのソース（freebase_mid、freebase_id）は拒否されます。
  • プロバイダーのフィルター： with_watch_providersにはwatch_regionが必要です。プロバイダーデータにはJustWatchの帰属表示要件があります。
  • ローカライズと画像： 再現性が重要な場合は、language=en-USと市場のregionを指定してください。画像URLは、/3/configurationのセキュアなベースURL、有効なサイズ、返されたパスから構築します。

使用する場面

映画やTVのメタデータ、出演者・スタッフ、公開情報、レーティング、画像、おすすめ作品、プロバイダーのメタデータを読み取り専用で検索する場合に、このスキルを使用します。

使用しない場面

トレントや海賊版の検索、ストリームの再生やダウンロード、個人の視聴済み・未視聴状態の管理には使用しないでください。視聴履歴のワークフローにはtraktを、配信状況の確認には再生・カタログ連携を使用してください。

リファレンスファイル

ファイル用途
references/auth-pagination-and-errors.md認証情報、ページネーション、レート制限、エラー、言語、地域、画像
references/find-and-details.mdIMDb/TVDB の検索、レスポンスのマッピング、詳細フィールド、複合リクエスト
references/search-discover-trending.md検索、ディスカバーフィルター、トレンド、ジャンル、レーティング、公開リスト

利用可能なスクリプトと前提条件

  • scripts/tmdb は、標準ライブラリと requests のみを使用する実行可能な Python CLI で、--json、--dry-run、--quiet、--verbose を維持します。
  • scripts/test_tmdb.py はオフラインの unittest/pytest スイートで、すべての HTTP 動作をモックします。
  • Python 3.8 以降と requests が必要です。このスキルによってサービスが起動されることはありません。

コメント

Markdown 対応