🎬 MCP Trakt：AI 的娱乐数据门户

MCP Trakt Built by AI+Humans Powered by Claude

一个模型上下文协议 (MCP) 服务器，在 AI 语言模型与 Trakt.tv API 之间建立桥梁，允许 LLM 访问实时娱乐数据和个人 Trakt 观看历史。该项目采用基于 FastMCP 的领域驱动架构，在身份验证、剧集、季、单集、电影、人物、用户数据、评论、搜索和签到功能之间实现了清晰的关注点分离。

🖥️ 一个 AI 实验

除了本段文字外，这里的所有内容（包括代码）均由 AI 生成。我的目标是深入了解 MCP，并且一直在使用 Cursor，因此将它们结合起来似乎是顺理成章的下一步。结果就诞生了这个项目。后续的所有更改也将由 AI 完成。

Related MCP server: FastAPI MCP Server

📚 关于 MCP 与 Trakt

模型上下文协议 (MCP) 使 AI 模型能够通过标准化工具和资源与外部系统进行交互。Trakt.tv 是一个用于追踪电视节目和电影的综合平台，拥有超过 1400 万用户和丰富的开发者 API。

🚀 快速入门

Docker 快速入门

docker run -d --rm --name trakt_mcpserver \
  -e TRAKT_CLIENT_ID=your_client_id \
  -e TRAKT_CLIENT_SECRET=your_client_secret \
  -p 8080:8080 \
  ghcr.io/wwiens/trakt_mcpserver:latest

本地安装

克隆此仓库

git clone https://github.com/yourusername/mcp-trakt.git
cd mcp-trakt

安装依赖
```
pip install -r requirements.txt
```

设置环境

cp .env.example .env

然后编辑 .env 文件以添加您的 Trakt API 凭据：

TRAKT_CLIENT_ID=your_client_id
TRAKT_CLIENT_SECRET=your_client_secret

运行服务器
```
python server.py
```

在 Claude Desktop 中安装

添加到您的 Claude Desktop MCP 配置文件中：

{
  "mcpServers": {
    "trakt": {
      "command": "python",
      "args": ["/path/to/your/server.py"],
      "env": {
        "TRAKT_CLIENT_ID": "your_client_id",
        "TRAKT_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

✨ 功能特性

🌎 公共 Trakt 数据

访问热门和流行的节目与电影
发现最受期待、收藏最多、播放最多和观看最多的内容
查看上周末美国票房最高的电影
获取来自 Trakt 全球社区的实时数据
格式化的响应，包含标题、年份和流行度指标
查看详细评分：包括节目和电影的平均分及分布情况
浏览剧集季：包含单集数量、已播出集数以及每季的评分
深入了解特定季：包含详细信息、单集列表、评分、演职员表、视频、翻译和互动统计数据
查看谁正在观看：实时查看当前正在观看特定季的用户
查找列表：查找包含特定季的列表
探索单集：包含详细摘要、评分、演职员表、视频、翻译和互动统计数据
查看谁正在观看：实时查看当前正在观看特定单集的用户
查找列表：查找包含特定单集的列表
查询演职员表：获取任何电影或节目的演职员信息，节目还可选客串明星
探索人物：包含传记、社交媒体和完整的影视作品列表
浏览人物作品：跨电影和节目的作品列表，包含角色名称和单集计数
查找列表：查找包含特定人物的列表

👤 个人 Trakt 数据

查看已观看节目：获取您个人观看过的完整节目列表
查看每个系列的最后观看日期
追踪您观看每个节目的次数
签到节目：为您当前正在观看的节目签到以标记为已观看
- 通过节目 ID（更精确）或节目标题（更方便）
- 在签到时包含自定义消息
- 以人类可读的格式查看您观看该集的时间
搜索节目：查找其详细信息和 ID
管理评分：支持分页查看、添加和删除电影、节目、季和单集的个人评分
管理关注列表：支持分页和排序查看、添加和删除关注列表中的项目
- 按类型过滤（全部、电影、节目、季、单集）
- 按多种标准排序（排名、添加时间、标题、发布时间、时长、流行度、百分比、投票数）
- 为关注列表项目添加可选备注（VIP 功能，500 字符限制）
追踪观看进度：查看任何电视节目的观看进度
- 查看已观看与已播出集数的对比及完成百分比
- 查看下一集待看内容
- 查看每季的进度统计分解
- 可选包含隐藏季和特别篇
管理播放进度：查看并清除已暂停的播放项目
- 查看您中途暂停的电影和单集
- 查看进度百分比和暂停时间
- 清除不再需要的播放项目
管理观看历史：从历史记录中添加和删除项目
- 将电影、节目、季或单集标记为已观看
- 可选指定观看时间
- 从观看历史中删除项目
通过设备代码流实现安全的 Trakt 身份验证
个人数据直接从您的 Trakt 账户获取

💬 评论与评价

查看节目和电影评论：阅读他人对您喜爱内容的评价
查看特定季和单集的评论：深入了解节目的特定部分
查看单条评论及其回复：参与社区讨论
剧透保护：默认隐藏包含剧透的评论
切换剧透可见性：选择显示或隐藏剧透
查看评价：更长、更详细的评论被标记为评价
查看评分分布：查看 1-10 分每个评分等级的用户数量

🔄 通用功能

通过 MCP 资源公开 Trakt API 数据
提供用于获取实时娱乐信息的工具
使 AI 模型能够提供个性化的娱乐推荐
简单的身份验证和注销流程
分页支持：适用于列表端点（趋势、流行、期待、收藏、播放、观看、搜索、评论、评分、关注列表）：
- 传入 page: int 获取单页结果及分页元数据
- 省略 page 可自动分页并返回最多 limit 个项目的扁平列表
- 使用 limit=0 获取所有可用结果（出于安全考虑上限为 100）

🔥 实时趋势数据

访问当前热门电视节目及实时观看人数
获取实时更新的热门电影
查看 Trakt 全球 1400 万+用户社区中的流行内容
示例：The White Lotus (2021), Daredevil: Born Again (2025), Black Bag (2025)

🔌 可用资源

MCP 资源提供 AI 模型可以访问的静态数据端点。这些 URI 通过标准化接口公开 Trakt 数据。

节目资源

资源	描述	示例数据
`trakt://shows/trending`	过去 24 小时内观看次数最多的节目	节目标题、年份、观看人数
`trakt://shows/popular`	基于评分的最受欢迎节目	节目标题、年份、流行度得分
`trakt://shows/anticipated`	按列表计数排序的最受期待节目	节目标题、年份、列表计数
`trakt://shows/favorited`	最受收藏的节目	节目标题、年份、收藏人数
`trakt://shows/played`	播放次数最多的节目	节目标题、年份、播放次数
`trakt://shows/watched`	独立用户观看次数最多的节目	节目标题、年份、观看人数

电影资源

资源	描述	示例数据
`trakt://movies/trending`	过去 24 小时内观看次数最多的电影	电影标题、年份、观看人数
`trakt://movies/popular`	基于评分的最受欢迎电影	电影标题、年份、流行度得分
`trakt://movies/anticipated`	按列表计数排序的最受期待电影	电影标题、年份、列表计数
`trakt://movies/favorited`	最受收藏的电影	电影标题、年份、收藏人数
`trakt://movies/played`	播放次数最多的电影	电影标题、年份、播放次数
`trakt://movies/watched`	独立用户观看次数最多的电影	电影标题、年份、观看人数
`trakt://movies/boxoffice`	上周末美国票房前 10 名电影	电影标题、年份、票房收入

用户资源

资源	描述	示例数据
`trakt://user/auth/status`	当前身份验证状态	身份验证状态、令牌过期时间
`trakt://user/watched/shows`	已认证用户观看过的节目	节目标题、年份、最后观看日期、播放次数
`trakt://user/watched/movies`	已认证用户观看过的电影	电影标题、年份、最后观看日期、播放次数

🛠️ 可用工具

MCP 工具是 AI 模型可以通过参数调用的交互式函数。使用这些工具来获取、搜索和管理 Trakt 数据。

# Get trending shows: auto-paginate up to 10 results
fetch_trending_shows(limit=10)

# Get trending shows: fetch ALL results (no limit)
fetch_trending_shows(limit=0)

# Get trending shows: single page with pagination metadata
fetch_trending_shows(limit=10, page=1)

# Get popular shows with optional limit parameter
fetch_popular_shows(limit=10)

# Get anticipated shows with optional limit parameter
fetch_anticipated_shows(limit=10)

# Get favorited shows with optional limit and period parameters
fetch_favorited_shows(limit=10, period="weekly")

# Get most played shows with optional limit and period parameters
fetch_played_shows(limit=10, period="weekly")

# Get most watched shows with optional limit and period parameters
fetch_watched_shows(limit=10, period="weekly")

# Search for shows: auto-paginate all results (omit page parameter)
search_shows(query="Breaking Bad", limit=5)

# Search for shows: single page with pagination metadata
search_shows(query="Breaking Bad", limit=5, page=1)

# Get ratings for a show
fetch_show_ratings(show_id="game-of-thrones")

# Get comprehensive show summary (includes air times, production status, ratings, metadata)
fetch_show_summary(show_id="game-of-thrones", extended=True)  # Default: comprehensive

# Get basic show summary (title, year, ID only)
fetch_show_summary(show_id="game-of-thrones", extended=False)

# Get videos for a show (with embedded markdown - default)
fetch_show_videos(show_id="game-of-thrones")

# Get videos for a show (simple text links)
fetch_show_videos(show_id="game-of-thrones", embed_markdown=False)

# Get related shows (similar shows based on genres, themes, and viewer patterns)
fetch_related_shows(show_id="game-of-thrones", limit=10)

# Get related shows with pagination metadata
fetch_related_shows(show_id="game-of-thrones", limit=10, page=1)

# Get all seasons for a show (includes episode counts, aired episodes, ratings)
fetch_show_seasons(show_id="game-of-thrones")

# Get cast and crew for a show
fetch_show_people(show_id="breaking-bad")

# Get cast, crew, and guest stars for a show
fetch_show_people(show_id="breaking-bad", include_guest_stars=True)

# Search for movies: auto-paginate all results (omit page parameter)
search_movies(query="The Godfather", limit=5)

# Search for movies: single page with pagination metadata
search_movies(query="The Godfather", limit=5, page=1)

# Get detailed info about a specific season
fetch_season_info(show_id="breaking-bad", season=1)

# Get all episodes for a season with ratings and runtime
fetch_season_episodes(show_id="breaking-bad", season=1)

# Get ratings and voting distribution for a season
fetch_season_ratings(show_id="breaking-bad", season=1)

# Get engagement stats (watchers, plays, collectors)
fetch_season_stats(show_id="breaking-bad", season=1)

# Get cast and crew for a season
fetch_season_people(show_id="breaking-bad", season=1)

# Get videos/trailers for a season (with embedded markdown - default)
fetch_season_videos(show_id="breaking-bad", season=1)

# Get videos for a season (simple text links)
fetch_season_videos(show_id="breaking-bad", season=1, embed_markdown=False)

# See who's watching a season right now
fetch_season_watching(show_id="breaking-bad", season=1)

# Get translations for a season (all languages)
fetch_season_translations(show_id="breaking-bad", season=1)

# Get translations for a specific language
fetch_season_translations(show_id="breaking-bad", season=1, language="es")

# Get lists containing a season
fetch_season_lists(show_id="breaking-bad", season=1)

# Get lists with type and sort filters
fetch_season_lists(show_id="breaking-bad", season=1, list_type="personal", sort="popular")

# Get detailed info about a specific episode
fetch_episode_summary(show_id="breaking-bad", season=1, episode=1)

# Get ratings and voting distribution for an episode
fetch_episode_ratings(show_id="breaking-bad", season=1, episode=1)

# Get engagement stats (watchers, plays, collectors)
fetch_episode_stats(show_id="breaking-bad", season=1, episode=1)

# Get cast and crew for an episode
fetch_episode_people(show_id="breaking-bad", season=1, episode=1)

# Get videos/trailers for an episode (with embedded markdown - default)
fetch_episode_videos(show_id="breaking-bad", season=1, episode=1)

# Get videos for an episode (simple text links)
fetch_episode_videos(show_id="breaking-bad", season=1, episode=1, embed_markdown=False)

# See who's watching an episode right now
fetch_episode_watching(show_id="breaking-bad", season=1, episode=1)

# Get translations for an episode (all languages)
fetch_episode_translations(show_id="breaking-bad", season=1, episode=1)

# Get translations for a specific language
fetch_episode_translations(show_id="breaking-bad", season=1, episode=1, language="es")

# Get lists containing an episode
fetch_episode_lists(show_id="breaking-bad", season=1, episode=1)

# Get lists with type and sort filters
fetch_episode_lists(show_id="breaking-bad", season=1, episode=1, list_type="personal", sort="popular")

# Get trending movies: auto-paginate all results (omit page parameter)
fetch_trending_movies(limit=10)

# Get trending movies: single page with pagination metadata
fetch_trending_movies(limit=10, page=1)

# Get popular movies with optional limit parameter
fetch_popular_movies(limit=10)

# Get anticipated movies with optional limit parameter
fetch_anticipated_movies(limit=10)

# Get favorited movies with optional limit and period parameters
fetch_favorited_movies(limit=10, period="weekly")

# Get most played movies with optional limit and period parameters
fetch_played_movies(limit=10, period="weekly")

# Get most watched movies with optional limit and period parameters
fetch_watched_movies(limit=10, period="weekly")

# Get the top 10 U.S. box office movies from last weekend
fetch_boxoffice_movies()

# Get ratings for a movie
fetch_movie_ratings(movie_id="tron-legacy-2010")

# Get comprehensive movie summary (includes production status, ratings, genres, runtime, certification, metadata)
fetch_movie_summary(movie_id="tron-legacy-2010", extended=True)  # Default: comprehensive

# Get basic movie summary (title, year, ID only)
fetch_movie_summary(movie_id="tron-legacy-2010", extended=False)

# Get videos for a movie (with embedded markdown - default)
fetch_movie_videos(movie_id="tron-legacy-2010")

# Get videos for a movie (simple text links)
fetch_movie_videos(movie_id="tron-legacy-2010", embed_markdown=False)

# Get related movies (similar movies based on genres, themes, and viewer patterns)
fetch_related_movies(movie_id="tron-legacy-2010", limit=10)

# Get related movies with pagination metadata
fetch_related_movies(movie_id="tron-legacy-2010", limit=10, page=1)

# Get cast and crew for a movie
fetch_movie_people(movie_id="the-dark-knight-2008")

# Get extended person details (biography, social media, birthday)
fetch_person_summary(person_id="bryan-cranston")

# Get basic person details (name and IDs only)
fetch_person_summary(person_id="bryan-cranston", extended=False)

# Look up by IMDB ID
fetch_person_summary(person_id="nm0186505")

# Get all movie credits for a person (cast roles and crew positions)
fetch_person_movies(person_id="bryan-cranston")

# Get all show credits for a person (with episode counts and series regular flags)
fetch_person_shows(person_id="bryan-cranston")

# Get lists containing a person (all types, sorted by popularity)
fetch_person_lists(person_id="bryan-cranston")

# Get lists with type and sort filters
fetch_person_lists(person_id="bryan-cranston", list_type="personal", sort="likes")

# Start the device authorization flow with Trakt
start_device_auth()

# Check the status of an ongoing authentication
check_auth_status()

# Clear authentication (logout)
clear_auth()

# Fetch shows watched by the authenticated user
fetch_user_watched_shows(limit=0)  # 0 for all shows

# Fetch movies watched by the authenticated user
fetch_user_watched_movies(limit=0)  # 0 for all movies

# Fetch user's personal ratings with pagination support
fetch_user_ratings(rating_type="movies", rating=10, page=1)

# Add new ratings for movies, shows, seasons, or episodes
add_user_ratings(rating_type="movies", items=[{"trakt_id": "314", "rating": 9}])

# Remove existing ratings by ID
remove_user_ratings(rating_type="movies", items=[{"trakt_id": "314"}])

# Fetch user's watchlist with pagination and sorting
fetch_user_watchlist(watchlist_type="all", sort_by="rank", sort_how="asc", page=1)

# Add items to watchlist with optional notes (VIP)
add_user_watchlist(watchlist_type="movies", items=[{"trakt_id": "314", "notes": "Must watch!"}])

# Remove items from watchlist
remove_user_watchlist(watchlist_type="movies", items=[{"trakt_id": "314"}])

# Method 1: Check in using show ID (recommended when precision is important)
# First use search_shows to find the correct show ID
search_shows(query="Breaking Bad", limit=5)
# Then use the ID for check-in
checkin_to_show(
    season=1,
    episode=3,
    show_id="1388",
    message="Loving this show!"
)

# Method 2: Check in using show title (more convenient)
checkin_to_show(
    season=1,
    episode=1,
    show_title="Breaking Bad",
    show_year=2008,  # Optional but helps with accuracy
    message="I'm the one who knocks!"
)

# Get comments for a movie: auto-paginate all results (omit page parameter)
fetch_movie_comments(movie_id="123", limit=10, show_spoilers=False)

# Get comments for a movie: single page with pagination metadata
fetch_movie_comments(movie_id="123", limit=10, show_spoilers=False, page=1)

# Get comments for a show: auto-paginate all results (omit page parameter)
fetch_show_comments(show_id="456", limit=10, show_spoilers=False, sort="likes")

# Get comments for a show: single page with pagination metadata
fetch_show_comments(show_id="456", limit=10, show_spoilers=False, sort="likes", page=1)

# Get comments for a specific season sorted by highest rating
fetch_season_comments(show_id="456", season=1, limit=10, show_spoilers=False, sort="highest")

# Get comments for a specific episode sorted by most replies
fetch_episode_comments(show_id="456", season=1, episode=3, limit=10, show_spoilers=False, sort="replies")

# Get a specific comment
fetch_comment(comment_id="789", show_spoilers=False)

# Get a comment with its replies sorted by oldest first
fetch_comment_replies(comment_id="789", limit=10, show_spoilers=False, sort="oldest")

# Get watched progress for a TV show
fetch_show_progress(show_id="breaking-bad")

# Get show progress with specials and hidden seasons included
fetch_show_progress(
    show_id="game-of-thrones",
    hidden=True,       # Include hidden seasons
    specials=True,     # Include season 0 (specials)
    count_specials=True,  # Count specials in overall stats
    last_activity="watched"  # Calculate next episode based on watched order
)

# Get detailed episode-by-episode progress with watch dates
fetch_show_progress(show_id="breaking-bad", verbose=True)

# Get paused playback progress (all types)
fetch_playback_progress()

# Get paused playback progress (movies only)
fetch_playback_progress(playback_type="movies")

# Get paused playback progress (episodes only)
fetch_playback_progress(playback_type="episodes")

# Remove a paused playback item (get ID from fetch_playback_progress)
remove_playback_item(playback_id=12345)

# Check if a movie has been watched (returns watch dates and count)
fetch_history(history_type="movies", item_id="314")  # The Dark Knight

# Check watch history for a show
fetch_history(history_type="shows", item_id="1388")  # Breaking Bad

# Browse all movie watch history
fetch_history(history_type="movies")

# Browse all watch history (all types)
fetch_history()

# Filter history by date range
fetch_history(
    history_type="movies",
    start_at="2024-01-01T00:00:00.000Z",
    end_at="2024-12-31T23:59:59.000Z"
)

# Add movies to watch history
add_to_history(
    history_type="movies",
    items=[{"trakt_id": "314"}]  # The Dark Knight
)

# Add movies with custom watched date
add_to_history(
    history_type="movies",
    items=[{"trakt_id": "314", "watched_at": "2024-01-15T20:30:00.000Z"}]
)

# Add episodes to watch history
add_to_history(
    history_type="episodes",
    items=[{"trakt_id": "62085"}]  # Breaking Bad S01E01
)

# Remove movies from watch history
remove_from_history(
    history_type="movies",
    items=[{"trakt_id": "314"}]
)

# Remove episodes from watch history
remove_from_history(
    history_type="episodes",
    items=[{"trakt_id": "62085"}]
)

📝 与 Claude 一起使用

安装完成后，Claude 可以使用此 MCP 服务器回答有关娱乐数据的问题。以下是一些入门示例。

“现在有哪些热门节目？”
“显示我观看过的节目”（需要身份验证）
“《权力的游戏》评分是多少？”

公共数据（无需身份验证）：

“现在最受期待的节目有哪些？”
“显示我最受期待的即将上映的电影”
“本周末有哪些电影上映？”
“显示当前票房最高的电影”
“你能推荐一些本周流行的电影吗？”
“本月观看次数最多的节目是什么？”
“搜索类似《绝命毒师》的节目”
“搜索类似《教父》的电影”
“显示《绝命毒师》的评论”
“人们对《教父》这部电影怎么看？”
“显示《怪奇物语》第一季的评论”
“获取《权力的游戏》第二季第五集的评论”
“显示评论 #12345 及其回复”
“显示《绝命毒师》的评论，但包含剧透”
“显示《绝命毒师》中点赞最多的评论”
“获取《教父》电影中评分最高的评论”
“显示《怪奇物语》第一季中回复最多的评论”
“显示《教父》的评分分布”
“《绝命毒师》评分有多高？”
“显示《创：战纪》的预告片”
“获取《权力的游戏》的视频”
“《教父》有哪些预告片？”
“获取《绝命毒师》的详细摘要”
“显示关于《教父》电影的详细信息”
“给我《权力的游戏》的基本信息”
“显示类似《绝命毒师》的节目”
“有哪些与《创：战纪》相关的电影？”
“查找类似《权力的游戏》的节目”
“告诉我关于《绝命毒师》第一季的信息”
“《权力的游戏》第二季有哪些单集？”
“《绝命毒师》第五季评分如何？”
“谁主演了《权力的游戏》第一季？”
“《绝命毒师》第一季有多受欢迎？”
“《怪奇物语》第二季有预告片吗？”
“谁现在正在观看《绝命毒师》第一季？”
“获取《绝命毒师》第一季的西班牙语翻译”
“哪些列表包含《绝命毒师》第一季？”
“告诉我关于《绝命毒师》试播集的信息”
“《权力的游戏》第一季第一集评分如何？”
“谁主演了《绝命毒师》第一集？”
“《绝命毒师》第五季第十六集有多受欢迎？”
“《怪奇物语》第一季第一集有预告片吗？”
“谁现在正在观看《绝命毒师》第一季第一集？”
“获取《绝命毒师》第一季第一集的西班牙语翻译”
“哪些列表包含《绝命毒师》第一季第一集？”
“谁主演了《蝙蝠侠：黑暗骑士》？”
“显示《绝命毒师》的演职员表”
“显示《绝命毒师》的客串明星”
“告诉我关于 Bryan Cranston 的信息”
“Bryan Cranston 演过哪些电影？”
“Bryan Cranston 出演过哪些电视节目？”
“哪些列表包含 Bryan Cranston？”

个人数据（需要身份验证）：

“我最后看的是什么节目？”
“显示我观看过的电影”
“我最后看的是什么电影？”
“我看过《蝙蝠侠：黑暗骑士》吗？”
“我看过《盗梦空间》吗？”
“我什么时候看的《黑客帝国》？”
“显示我评分为 10/10 的电影”
“给《绝命毒师》添加 9/10 的评分”
“显示我的关注列表”
“我的关注列表里有哪些电影？”
“将《教父》添加到我的关注列表”
“将《绝命毒师》添加到我的关注列表并附带备注”（VIP）
“从我的关注列表中删除《蝙蝠侠：黑暗骑士》”
“按添加时间排序显示我的关注列表”
“为《绝命毒师》第二季第五集签到”
“为节目 ID 1388 的第一季第三集签到”
“我在《绝命毒师》上的进度如何？”
“我《权力的游戏》看到哪里了？”
“我《怪奇物语》的下一集是什么？”
“显示我暂停的电影或单集”
“清除那部电影的暂停播放记录”
“将《蝙蝠侠：黑暗骑士》标记为已观看”
“将《绝命毒师》第一季添加到我的观看历史”
“从我的观看历史中删除《盗梦空间》”

👤 个人数据访问

通过身份验证，您可以访问：

您完整的节目

Trakt