🎬 MCP Trakt: 通往娱乐数据的AI门户

这是一个模型上下文协议（MCP）服务器，它在AI语言模型与Trakt.tv API之间架起了一座桥梁，允许大型语言模型访问实时娱乐数据和个人Trakt观看历史。

🖥️ 一个AI实验

除了这一段落外，这里的所有内容都是由AI生成的，包括代码。我的目标是更多地了解MCP，并且一直在大量使用Cursor，因此将这两者结合起来似乎是自然而然的下一步。结果就是这个项目。未来所有的更改也将由AI完成。

🤖 什么是MCP？

模型上下文协议（MCP）是一个开放规范，它使像Claude这样的大型语言模型能够与外部系统和数据源进行交互。

MCP为AI模型提供了标准化的方式来：

• 访问超出其训练截止日期后的实时数据
• 通过专用服务器连接到外部API和Web服务
• 安全地执行专门的工具和功能
• 读取和写入外部资源
• 处理在纯文本格式中难以处理的复杂数据

MCP的核心工作原理在于定义了以下几点：

1. 资源：AI可以从中读取或写入的结构化数据源（如trakt://shows/trending）
2. 工具：AI可以调用来执行特定操作的功能（如fetch_trending_shows）
3. 会话：AI与MCP服务器之间的安全连接

像这样的MCP服务器充当AI模型与外部世界之间的桥梁，使得它们可以在不需要重新训练的情况下扩展新的能力。

📺 什么是Trakt？

Trakt.tv 是一个自动跟踪你观看的电视剧和电影的平台。该服务提供：

• 跨多个流媒体服务的全面观看习惯跟踪
• 社交功能，让你可以与朋友分享和讨论正在观看的内容
• 基于你的观看历史的个性化推荐
• 开发人员可以用来构建应用程序的广泛API

Trakt已成为娱乐跟踪的标准，拥有：

• 超过1400万用户跟踪他们的观看习惯
• 数百万部电影和电视剧的数据，包括详细的元数据
• 与流行的媒体播放器和流媒体服务集成

此MCP服务器利用Trakt丰富的API生态系统，将实时娱乐数据直接带到您与像Claude这样的AI助手的对话中。

🚀 Cursor开发体验

整个项目是使用Cursor开发的，这是一个专为AI时代打造的代码编辑器，所有代码均由Claude 3.7 Sonnet生成。这种方法展示了：

• AI辅助开发如何显著加速专业MCP服务器的构建
• 现代AI编写功能性、结构良好的代码的能力
• 人类意图与AI实现之间的协作工作流程

✨ 功能

🌎 公共Trakt数据

• 访问趋势和热门节目及电影
• 发现最受欢迎、播放最多和观看最多的内容
• 从Trakt的全球社区获取实时数据
• 格式化的响应，包含标题、年份和受欢迎程度指标
• 查看详细评分，包括平均分数和分布

👤 个人Trakt数据

• 查看您已观看的节目：获取您个人观看过的完整节目列表
• 查看每个系列的确切最后观看日期
• 跟踪您观看每个节目的次数
• 签到当前正在观看的节目以标记为已观看
  • 通过节目ID（更精确）或节目名称（更方便）
  • 将签到分享到Twitter、Mastodon或Tumblr
  • 在签到时包含自定义消息- 查看以人类可读格式显示的观看剧集的时间
• 搜索节目以查找其详细信息和ID
• 通过设备代码流与Trakt进行安全认证
• 个人数据直接从您的Trakt帐户中获取

💬 评论与评价

• 查看节目和电影的评论：阅读其他人对您喜爱的内容的看法
• 查看特定季度和剧集的评论：了解关于节目的特定部分的观点
• 查看单条评论及其回复：参与社区讨论
• 剧透保护：默认情况下隐藏包含剧透的评论
• 切换剧透可见性：选择是否显示或隐藏剧透
• 查看评价：更长、更详细的评论被标记为评价
• 查看评分分布：查看有多少用户给出了1到10分中的每个评分

🔄 通用功能

• 通过MCP资源暴露Trakt API数据
• 提供工具以获取实时娱乐信息
• 使AI模型能够提供个性化的娱乐推荐
• 简单的认证和登出过程

📺 当前热门电视剧

截至2025年4月，您可以访问如下趋势电视剧：

• "白莲花" (2021) - 7,870名观众
• "夜魔侠：重生" (2025) - 6,738名观众
• "分离" (2022) - 4,507名观众

🎥 当前热门电影

当前最热的电影包括：

• "黑包" (2025) - 1,491名观众
• "一个工人" (2025) - 1,226名观众
• "米奇17" (2025) - 764名观众

🔌 可用资源

节目资源

资源	描述	示例数据
trakt://shows/trending	过去24小时内最受关注的节目	节目名称、年份、观众数
trakt://shows/popular	根据评分最受欢迎的节目	节目名称、年份、受欢迎程度得分
trakt://shows/favorited	最受收藏的节目	节目名称、年份、收藏次数
trakt://shows/played	播放次数最多的节目	节目名称、年份、播放次数
trakt://shows/watched	由唯一用户观看次数最多的节目	节目名称、年份、观看者数量

电影资源

资源	描述	示例数据
trakt://movies/trending	过去24小时内最受关注的电影	电影名称、年份、观众数
trakt://movies/popular	根据评分最受欢迎的电影	电影名称、年份、受欢迎程度得分
trakt://movies/favorited	最受收藏的电影	电影名称、年份、收藏次数
trakt://movies/played	播放次数最多的电影	电影名称、年份、播放次数
trakt://movies/watched	由唯一用户观看次数最多的电影	电影名称、年份、观看者数量

用户资源

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

评论资源

资源	描述	示例数据
trakt://comments/movie/:id	特定电影的评论	评论文本、作者、日期、点赞数
trakt://comments/show/:id	特定节目的评论	评论文本、作者、日期、点赞数
trakt://comments/show/:id/season/:season	特定季度的评论	评论文本、作者、日期、点赞数
trakt://comments/show/:id/season/:season/episode/:episode	特定剧集的评论	评论文本、作者、日期、点赞数
trakt://comments/:id	特定评论	评论文本、作者、日期、点赞数
trakt://comments/:id/replies	对特定评论的回复	回复文本、作者、日期

评分资源

| 资源 | 描述 | 示例数据 ||----------|-------------|--------------|
| trakt://shows/:id/ratings | 特定剧集的评分 | 平均评分、投票数、分布 |
| trakt://movies/:id/ratings | 特定电影的评分 | 平均评分、投票数、分布 |

🛠️ 可用工具

剧集工具

python

获取趋势剧集，可选参数 limit

fetch_trending_shows(limit=10)

获取热门剧集，可选参数 limit

fetch_popular_shows(limit=10)

获取收藏剧集，可选参数 limit 和 period

fetch_favorited_shows(limit=10, period="weekly")

获取播放最多的剧集，可选参数 limit 和 period

fetch_played_shows(limit=10, period="weekly")

获取观看最多的剧集，可选参数 limit 和 period

fetch_watched_shows(limit=10, period="weekly")

通过标题搜索剧集以获取剧集ID和详细信息

search_shows(query="Breaking Bad", limit=5)

通过标题搜索电影以获取电影ID和详细信息

search_movies(query="The Godfather", limit=5)

电影工具

python

获取趋势电影，可选参数 limit

fetch_trending_movies(limit=10)

获取热门电影，可选参数 limit

fetch_popular_movies(limit=10)

获取收藏电影，可选参数 limit 和 period

fetch_favorited_movies(limit=10, period="weekly")

获取播放最多的电影，可选参数 limit 和 period

fetch_played_movies(limit=10, period="weekly")

获取观看最多的电影，可选参数 limit 和 period

fetch_watched_movies(limit=10, period="weekly")

认证与用户工具

python

开始 Trakt 的设备授权流程

start_device_auth()

检查正在进行中的认证状态

check_auth_status()

清除认证（登出）

clear_auth()

获取已认证用户的观看剧集

fetch_user_watched_shows(limit=0) # 0 表示所有剧集

获取已认证用户的观看电影

fetch_user_watched_movies(limit=0) # 0 表示所有电影

签到工具

python

方法 1：使用剧集ID签到（当需要高精度时推荐）

首先使用 search_shows 查找正确的剧集ID

search_shows(query="Breaking Bad", limit=5)

然后使用 ID 进行签到

checkin_to_show(
season=1,
episode=3,
show_id="1388",
message="Loving this show!"
)

方法 2：使用剧集名称签到（更方便）

checkin_to_show(
season=1,
episode=1,
show_title="Breaking Bad",
show_year=2008, # 可选但有助于提高准确性
message="I m the one who knocks!",
share_twitter=True,
share_mastodon=False,
share_tumblr=False
)

评论工具

python

获取电影的评论（默认按最新排序）

fetch_movie_comments(movie_id="123", limit=10, show_spoilers=False)

获取剧集的评论并按点赞数排序

fetch_show_comments(show_id="456", limit=10, show_spoilers=False, sort="likes")

获取特定季度的评论并按最高评分排序

fetch_season_comments(show_id="456", season=1, limit=10, show_spoilers=False, sort="highest")

获取特定剧集的评论并按回复数排序

fetch_episode_comments(show_id="456", season=1, episode=3, limit=10, show_spoilers=False, sort="replies")

获取特定评论

fetch_comment(comment_id="789", show_spoilers=False)

获取特定评论及其回复，并按最旧优先排序

fetch_comment_replies(comment_id="789", limit=10, show_spoilers=False, sort="oldest")

评分工具

python

获取剧集的评分

fetch_show_ratings(show_id="game-of-thrones")

获取电影的评分

fetch_movie_ratings(movie_id="tron-legacy-2010")

🔐 认证

服务器使用 Trakt 的设备认证流程：

1. 当您请求特定于用户的数据时，如果需要，服务器将自动启动认证。
2. 您将收到一个代码和一个浏览器访问的 URL。3. 在Trakt网站上输入代码并授权应用后，告知Claude你已完成授权。
3. Claude会检查认证状态，然后获取你的个人数据。
4. 你的认证令牌将被安全地存储以供将来请求使用。

你可以随时使用clear_auth工具注销。

🚀 设置

1. 克隆此仓库
   bash
   git clone https://github.com/yourusername/mcp-trakt.git
   cd mcp-trakt

2. 安装依赖
   bash
   pip install -r requirements.txt

3. 设置环境
   bash
   cp .env.example .env

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

   TRAKT_CLIENT_ID=your_client_id
   TRAKT_CLIENT_SECRET=your_client_secret

4. 运行服务器
   bash
   python server.py

🧪 开发与测试

使用MCP Inspector进行测试

bash
mcp dev server.py

在Claude桌面版中安装

bash
mcp install server.py

运行测试

bash

安装测试依赖

pip install -r requirements-dev.txt

运行所有测试

pytest

以详细输出运行

pytest -v -s

📝 与Claude一起使用

安装完成后，你可以向Claude提出如下问题：

• "现在哪些剧集正在流行？"
• "你能推荐一些本周热门电影吗？"
• "本月观看次数最多的剧集是什么？"
• "显示我已观看的剧集"（需要认证）
• "我最后观看的是哪部剧集？"（需要认证）
• "显示我已观看的电影"（需要认证）
• "我最后观看的是哪部电影？"（需要认证）
• "搜索像《绝命毒师》这样的剧集"
• "为《绝命毒师》第二季第五集签到"（使用标题）
• "为ID为1388的剧集第一季第三集签到，并在Twitter上分享"（使用ID）
• "显示关于《绝命毒师》的评论"
• "人们对于《教父》这部电影怎么说？"
• "显示关于《怪奇物语》第一季的评论"
• "获取《权力的游戏》第二季第五集的评论"
• "显示编号为12345的评论及其回复"
• "显示关于《绝命毒师》的评论，包括剧透"
• "搜索像《教父》这样的电影"
• "显示关于《绝命毒师》最受欢迎的评论"（使用sort="likes"）
• "获取关于《教父》评分最高的评论"（使用sort="highest"）
• "显示关于《怪奇物语》第一季回复最多的评论"（使用sort="replies"）
• "《权力的游戏》的评分是多少？"
• "显示《教父》的评分分布"
• "《绝命毒师》的评分有多高？"

Claude将使用这个MCP服务器为你提供来自Trakt的实时数据。

👤 个人数据访问

通过认证，你可以访问：

• 你完整的观看历史记录（包括剧集和电影）
• 每个剧集和电影的最后观看日期
• 你观看每个剧集和电影的次数
• 对当前正在观看的剧集进行签到并跟踪进度
• 个人观看统计数据
• 在社交媒体平台上分享你的观看活动

所有数据都是直接从你的Trakt账户实时获取的。

🔮 未来开发

• 扩展用户认证以访问更多个人数据
• 添加即将到来的剧集的日历事件
• 支持scrobbling（追踪你正在观看的内容）
• 根据观看历史实现推荐功能
• 增加对更多社交媒体平台的支持以便分享

📄 许可证

MIT许可证

---