Korean Entertainment

韩国影视 MCP 服务

一款面向韩国电影和电视剧的生产级 MCP（Model Context Protocol）服务，整合了 10 个数据源，并通过 Descope 部署 OAuth 2.1 身份验证。

在线端点： https://kr-movie-tv-mcp-production.up.railway.app/mcp

---

功能介绍

该服务提供 17 个工具，让 AI Agent 能查询统一的韩国娱乐数据库，无需再访问 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 社区标签筛选电视剧（Bromance、Time Travel、Revenge 等）

详情

工具	描述
get_movie	电影完整详情，包含全部 5 个评分来源
get_drama	电视剧完整详情，包含全部评分来源
get_cast	演员列表，包含角色名称和角色类型
get_episode_ratings	Nielsen Korea 每集收视率百分比
get_ost_albums	OST 专辑及 Naver Vibe 流媒体链接

实用工具

工具	描述
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）

社区评分、集数、播出状态，以及独有的社区生成标签（“Bromance”“Time Travel”“CEO Male Lead”）。其他来源都没有结构化的韩剧标签。

4. HanCinema — 网页爬虫（Playwright）

韩国电影和电视剧的历史元数据，包括 TMDB 未涵盖的旧作品。

5. Naver Movies — 网页爬虫（Playwright）

提供两项独特的韩国观众电影评分：

• 실관람객 평점（已验证购票观众评分）— 关联实际影院购票记录
• 네티즌 평점（网民评分）— 韩国公众评分

6. Naver TV — 网页爬虫（Playwright）

从 SVG 图表元素中提取 Nielsen Korea 每集收视率。没有任何英文数据源提供此数据。此外还会抓取 Naver Vibe 上的 OST 专辑。

7. JustWatch — 网页爬虫（Playwright）

提供美国、英国、加拿大和澳大利亚 364 多家服务提供商的观看信息，包括变现类型、价格和画质。

8. Wikipedia — 官方 REST API

剧情简介、制作背景和影评反馈章节。章节别名系统可处理非标准文章名称。

9. 奖项 — 网页爬虫（httpx + Playwright）

涵盖韩国五大颁奖典礼：

• KBS、MBC、SBS 演技大赏（来自 AsianWiki）
• 青龙电影奖和青龙系列大奖（OTT）
• 百想艺术大赏（来自官方网站）

10. KMDb — 等待 API 审批

---

数据库架构

基于 Supabase（PostgreSQL），使用免费套餐。

11 张表

表	描述
movies	约 9,983 部韩国电影，包含所有跨来源 ID 和评分
tv_shows	约 3,500 多部韩国剧集，包含 MDL/Naver/TMDB 数据
people	演员和导演（共享查询表）
movie_cast	电影与人员的关系
show_cast	剧集与人员的关系
episodes	每集的 Nielsen Korea 评分
ost_albums	剧集 OST 专辑及 Vibe 链接
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
• 传输方式： Streamable 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 → 设置 → 连接器
2. 点击 添加自定义连接器
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：市场上架	🔄 进行中