Korean Entertainment

韓国エンターテインメント MCP サーバー

韓国の映画とテレビ番組向けに構築された、本番環境対応の MCP（Model Context Protocol）サーバーです。10 のデータソースを統合し、Descope による OAuth 2.1 認証を使用してデプロイされています。

ライブエンドポイント： https://kr-movie-tv-mcp-production.up.railway.app/mcp

---

このサーバーの機能

このサーバーは 17 個のツールを公開し、AI エージェントが統合された韓国エンターテインメントデータベースを検索できるようにします。これまでは 6 つ以上の別々のウェブサイトを訪問する必要があったデータを統合しています。

• 韓国および海外の評価（Nielsen Korea、Naver、MDL、TMDB、Rotten Tomatoes）
• Nielsen Korea によるエピソードごとの視聴率推移
• 米国／英国／カナダ／オーストラリアでの JustWatch の配信状況
• KOBIS 公式の韓国興行ランキング
• 韓国の主要な 5 つの授賞式における受賞履歴
• Naver Vibe へのリンク付き OST アルバム
• 韓国語名で検索できるキャストの出演作品一覧

---

MCP ツール

検索

ツール	説明
search_titles	英語または韓国語のタイトルで映画やドラマを検索します
get_trending_dramas	現在放送中のドラマを MDL 評価順に表示します
get_top_dramas	完結済みドラマの歴代ランキングを表示します。ジャンルで絞り込めます
get_top_movies	韓国映画のランキングを表示します。ジャンル／年／評価で絞り込めます
browse_by_genre	映画またはドラマをジャンルで絞り込みます
browse_by_tag	MDL コミュニティタグ（ブロマンス、タイムトラベル、復讐など）でドラマを絞り込みます

詳細

ツール	説明
get_movie	5 つの評価ソースすべてを含む、映画の詳細情報を取得します
get_drama	すべての評価ソースを含む、ドラマの詳細情報を取得します
get_cast	役名と役柄の種類を含むキャスト一覧を取得します
get_episode_ratings	Nielsen Korea によるエピソードごとの視聴率（％）を取得します
get_ost_albums	Naver Vibe のストリーミングリンク付き OST アルバムを取得します

ユーティリティ

ツール	説明
find_where_to_watch	タイトルと地域を指定して配信状況を検索します
find_by_provider	地域内で Netflix／Viki などが配信する韓国コンテンツをすべて検索します
get_weekly_boxoffice	KOBIS の韓国興行ランキングを取得します
get_actor_filmography	俳優または監督の出演作品一覧を取得します
get_awards	作品の受賞履歴、または授賞式の特定年の受賞履歴全体を取得します
compare_ratings	すべてのソースの評価を並べて比較します

---

データソース

1. TMDB — 公式 API

韓国の映画とテレビ番組全般の基本メタデータ（タイトル、キャスト、ジャンル、評価、ポスター画像）を提供します。約 9,983 本の映画と 3,500 以上の番組でデータベースを初期構築します。

2. KOBIS（韓国映画振興委員会）— 公式 API

韓国の公式週間・日別興行ランキング、累計観客動員数、興行収入、上映スクリーン数を提供します。信頼できる韓国の劇場公開データを提供する唯一のソースです。

3. MyDramaList — ウェブスクレーパー（Playwright）

コミュニティ評価、エピソード数、放送状況に加え、独自のコミュニティ生成タグ（「ブロマンス」「タイムトラベル」「CEO の男性主人公」など）を提供します。K ドラマのタグを構造化データとして持つソースはほかにありません。

4. HanCinema — ウェブスクレーパー（Playwright）

TMDB がカバーしていない古い作品を含む、韓国映画やドラマの過去のメタデータを提供します。

5. Naver Movies — ウェブスクレーパー（Playwright）

映画に対する、韓国の観客独自の評価を 2 種類提供します。

• 실관람객 평점（実際にチケットを購入した観客の評価）— 実際の映画館での購入に紐づいています
• 네티즌 평점（ネットユーザー評価）— 韓国の一般視聴者による評価

6. Naver TV — ウェブスクレーパー（Playwright）

SVG チャート要素から抽出した、Nielsen Korea によるエピソードごとの視聴率を提供します。このデータを持つ英語のソースはありません。また、Naver Vibe から OST アルバムも取得します。

7. JustWatch — ウェブスクレーパー（Playwright）

米国、英国、カナダ、オーストラリアの 364 以上の配信サービスの視聴先データを提供します。収益化方式、価格、画質も含まれます。

8. Wikipedia — 公式 REST API

あらすじ、制作背景、批評家の評価に関するセクションを提供します。セクションの別名システムにより、標準外の記事名にも対応します。

9. 賞 — ウェブスクレーパー（httpx + Playwright）

韓国の主要な授賞式 5 つに対応します。

• KBS、MBC、SBS 演技大賞（AsianWiki から取得）
• 青龍映画賞 + 青龍シリーズアワード（OTT）
• 百想芸術大賞（公式サイトから取得）

10. KMDb — API 承認待ち

---

データベーススキーマ

Supabase（PostgreSQL）上に構築されており、無料プランを利用しています。

11 個のテーブル

テーブル	説明
movies	各ソースの ID と評価をすべて含む、約 9,983 本の韓国映画
tv_shows	MDL／Naver／TMDB のデータを含む、約 3,500 本以上の韓国ドラマ
people	俳優と監督（共通参照用）
movie_cast	映画と人物の関係
show_cast	番組と人物の関係
episodes	各エピソードの Nielsen Korea の評価
ost_albums	Vibe のリンクを含むドラマの OST アルバム
awards	5 つの授賞式における受賞者
award_nominees	各賞カテゴリのノミネート作品
streaming_availability	タイトル／地域／プロバイダーごとの配信状況
boxoffice	KOBIS の週次興行収入データ

評価フィールドの命名規則

すべての評価フィールドは、ソースを明示する名前が付けられています。

tmdb_rating              -- Global community (0-10)
mdl_rating               -- International K-drama fans (0-10)
naver_audience_rating    -- Korean verified ticket buyers (0-10)
naver_netizen_rating     -- Korean general public (0-10)
naver_latest_rating      -- Nielsen Korea latest episode (%)
naver_highest_rating     -- Nielsen Korea peak episode (%)
rt_tomatometer           -- Western professional critics (0-100%)
rt_audience_score        -- Western RT users (0-100%)

---

アーキテクチャ

GitHub Actions (scheduling)
    ↓
Prefect flows (retry logic, task caching, logging)
    ↓
data_sources/* (Playwright + httpx + REST APIs)
    ↓
pipeline/utils.py (data normalization)
    ↓
db/queries.py (upsert operations)
    ↓
Supabase (PostgreSQL + PostgREST)
    ↓
server.py (FastMCP + Descope OAuth 2.1)
    ↓
Railway (always-on hosting)

同期スケジュール

ジョブ	スケジュール	同期する内容
sync_tmdb	毎晩 UTC 2 時	新しい韓国作品、評価の更新
sync_mydramalist	毎晩 UTC 3 時	放送状況、MDL の評価、タグ
sync_naver_tv	毎晩 UTC 4 時	放送中の番組のエピソード評価
sync_kobis	毎週月曜日	韓国の興行収入
sync_justwatch	毎週水曜日	配信状況（200 タイトル）
sync_wikipedia	毎週木曜日	あらすじ（新しいタイトルのみ）
sync_awards	毎週日曜日	授賞式データ

---

リポジトリ構成

kr-movie-tv-mcp/
├── data_sources/          # One file per data source
│   ├── tmdb.py
│   ├── kobis.py
│   ├── mydramalist.py
│   ├── hancinema.py
│   ├── naver.py
│   ├── naver_tv.py
│   ├── justwatch.py
│   ├── wikipedia.py
│   └── awards.py
├── db/
│   ├── models.py          # Field documentation
│   └── queries.py         # All DB read/write operations
├── pipeline/
│   ├── utils.py           # Shared helpers
│   ├── orchestrator.py    # Master flow
│   └── jobs/              # One sync job per source
├── scripts/               # GitHub Actions runner scripts
├── tests/                 # One test file per data source
├── .github/workflows/
│   ├── nightly.yml
│   ├── weekly.yml
│   └── initial_population.yml
├── server.py              # FastMCP MCP server
├── schema.sql             # Full Supabase schema
├── railway.toml           # Railway deployment config
└── requirements.txt

---

デプロイ

MCP サーバー

• ホスティング： Railway（月額 $5、常時稼働）
• 認証： FastMCP の DescopeProvider を介した Descope OAuth 2.1
• トランスポート： ストリーマブル HTTP
• エンドポイント： https://kr-movie-tv-mcp-production.up.railway.app/mcp

パイプライン

• スケジューリング： GitHub Actions（月 2,000 分まで無料）
• オーケストレーション： Prefect（再試行ロジック、タスクのキャッシュ）
• データベース： Supabase の無料プラン（500MB、API リクエスト無制限）

---

環境変数

# Supabase
SUPABASE_URL=
SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

# Pipeline sources
TMDB_API_KEY=
KOBIS_API_KEY=

# Descope auth (for MCP server)
DESCOPE_CONFIG_URL=    # .well-known URL from Descope console
SERVER_URL=            # Railway public URL

---

Claude への接続

1. claude.ai → Settings → Connectors に移動します
2. Add custom connector をクリックします
3. 次を貼り付けます：https://kr-movie-tv-mcp-production.up.railway.app/mcp
4. Descope OAuth フローを完了します

---

既知の制限事項

• Rotten Tomatoes： RT が HTML を変更するとパッケージが動作しなくなります。現在は除外されています。
• 韓国の配信プラットフォーム（TVING、Wavve、Coupang）： 韓国の電話番号が必要です。除外されています。
• KMDb： API の利用申請は承認待ちです。
• JustWatch の初回データ投入： 4 つの地域を対象に、タイトルごとに約 85 秒かかります。週次同期では一度に 200 タイトルを追加します。
• テレビ番組： 約 10,000 件のうち約 3,500 件を同期済みです（初回データ投入時に GitHub Actions の 6 時間のタイムアウトに到達）。夜間同期で引き続き不足分を補います。
• 放送状況： MDL の同期完了前に追加された番組は、状況が誤っている場合があります。時間の経過とともに解消されます。

---

フェーズの状況

フェーズ	状況
フェーズ 1：データソース（10 ソース）	✅ 完了
フェーズ 2：データベーススキーマ（11 テーブル）	✅ 完了
フェーズ 3：パイプラインジョブ＋GitHub Actions	✅ 完了
フェーズ 4：MCP サーバー（FastMCP + Descope + Railway）	✅ 完了
フェーズ 5：マーケットプレイスへの掲載	🔄 進行中