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

一个模型上下文协议 (MCP) 服务器，它在 AI 语言模型和 Trakt.tv API 之间创建桥梁，允许 LLM 访问实时娱乐数据和个人 Trakt 观看历史。

🖥️ 一个 AI 实验

除了本段文字，这里的一切，包括代码，都是由 AI 生成的。我的目标是更多地了解 MCP，并且一直在使用 Cursor，因此将它们结合起来似乎是很自然的下一步。结果就是这个项目。未来所有的更改也将由 AI 完成。

🤖 什么是 MCP？

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

MCP 为 AI 模型创建了一种标准化的方式来：

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

MCP 的核心工作原理是定义：

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

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

📺 什么是 Trakt？

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

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

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

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

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

🚀 Cursor 开发体验

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

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

✨ 功能

🌎 公共 Trakt 数据

• 访问热门和流行的电视节目和电影
• 发现最受欢迎、播放和观看的内容
• 从 Trakt 的全球社区获取实时数据
• 格式化的响应，包含标题、年份和受欢迎程度指标

👤 个人 Trakt 数据

• 查看您观看的节目 (View Your Watched Shows)：获取您个人观看过的节目的完整列表
• 查看每个系列的准确的上次观看日期
• 跟踪您观看每个节目的次数
• 签到 (Check in) 您当前正在观看的节目，将其标记为已观看
  • 通过节目 ID（更精确）或节目标题（更方便）
  • 将签到分享到 Twitter、Mastodon 或 Tumblr
  • 在您的签到中包含自定义消息
  • 以人类可读的格式查看您观看剧集的时间
• 搜索节目 (Search for shows) 以查找其详细信息和 ID
• 通过设备代码流程与 Trakt 进行安全身份验证
• 个人数据直接从您的 Trakt 帐户获取

🔄 一般功能

• 通过 MCP 资源公开 Trakt API 数据
• 提供用于获取实时娱乐信息的工具
• 使 AI 模型能够提供个性化的娱乐推荐
• 简单的身份验证和注销过程

📺 当前热门节目

截至 2025 年 4 月，您可以访问热门节目，例如：

• "The White Lotus" (2021) - 7,870 名观看者
• "Daredevil: Born Again" (2025) - 6,738 名观看者
• "Severance" (2022) - 4,507 名观看者

🎥 当前热门电影

现在最热门的电影：

• "Black Bag" (2025) - 1,491 名观看者
• "A Working Man" (2025) - 1,226 名观看者
• "Mickey 17" (2025) - 764 名观看者

🔌 可用资源

节目资源

资源 (Resource)	描述 (Description)	示例数据 (Example Data)
trakt://shows/trending	过去 24 小时内观看次数最多的节目	节目标题、年份、观看者人数
trakt://shows/popular	基于评分的最受欢迎的节目	节目标题、年份、受欢迎程度评分
trakt://shows/favorited	最受欢迎的节目	节目标题、年份、收藏人数
trakt://shows/played	播放次数最多的节目	节目标题、年份、播放次数
trakt://shows/watched	唯一用户观看次数最多的节目	节目标题、年份、观看者人数

电影资源

资源 (Resource)	描述 (Description)	示例数据 (Example Data)
trakt://movies/trending	过去 24 小时内观看次数最多的电影	电影标题、年份、观看者人数
trakt://movies/popular	基于评分的最受欢迎的电影	电影标题、年份、受欢迎程度评分
trakt://movies/favorited	最受欢迎的电影	电影标题、年份、收藏人数
trakt://movies/played	播放次数最多的电影	电影标题、年份、播放次数
trakt://movies/watched	唯一用户观看次数最多的电影	电影标题、年份、观看者人数

用户资源

资源 (Resource)	描述 (Description)	示例数据 (Example Data)
trakt://user/auth/status	当前身份验证状态	身份验证状态、令牌过期时间
trakt://user/watched/shows	经过身份验证的用户观看的节目	节目标题、年份、上次观看日期、播放次数
trakt://user/watched/movies	经过身份验证的用户观看的电影	电影标题、年份、上次观看日期、播放次数

🛠️ 可用工具

节目工具

# 获取热门节目，带有可选的 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)

电影工具

# 获取热门电影，带有可选的 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")

身份验证和用户工具

# 启动与 Trakt 的设备授权流程
start_device_auth()

# 检查正在进行的身份验证的状态
check_auth_status()

# 清除身份验证（注销）
clear_auth()

# 获取经过身份验证的用户观看的节目
fetch_user_watched_shows(limit=0)  # 0 表示所有节目

# 获取经过身份验证的用户观看的电影
fetch_user_watched_movies(limit=0)  # 0 表示所有电影

签到工具

# 方法 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
)

🔐 身份验证

服务器使用 Trakt 的设备身份验证流程：

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

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

🚀 设置

1. 克隆此存储库

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

2. 安装依赖项

   pip install -r requirements.txt
   

3. 设置您的环境

   cp .env.example .env
   

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

   TRAKT_CLIENT_ID=your_client_id
   TRAKT_CLIENT_SECRET=your_client_secret
   

4. 运行服务器

   python server.py
   

🧪 开发和测试

使用 MCP Inspector 进行测试

mcp dev server.py

在 Claude Desktop 中安装

mcp install server.py

📝 与 Claude 一起使用

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

• "现在有哪些热门节目？"
• "你能推荐一些本周流行的电影吗？"
• "本月观看次数最多的节目是什么？"
• "显示我观看过的节目"（需要身份验证）
• "我上次观看的节目是什么？"（需要身份验证）
• "显示我观看过的电影"（需要身份验证）
• "我上次观看的电影是什么？"（需要身份验证）
• "搜索像 'Breaking Bad' 这样的节目"
• "签到 Breaking Bad 第 2 季第 5 集"（使用标题）
• "签到节目 ID 为 1388 的第 1 季第 3 集，并在 Twitter 上分享"（使用 ID）

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

👤 个人数据访问

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

• 您完整的观看过的节目和电影历史记录
• 每个节目和电影的上次观看日期
• 您观看每个节目和电影的次数
• 签到您当前正在观看的节目并跟踪您的进度
• 个人观看统计信息
• 在社交媒体平台上分享您的观看活动

所有数据都直接从您的 Trakt 帐户实时获取。

🔮 未来发展

• 扩展用户身份验证以访问更多个人数据
• 为即将播出的剧集添加日历事件
• 支持 scrobbling（跟踪您正在观看的内容）
• 根据观看历史记录实施推荐
• 扩展搜索以包括电影以及节目
• 添加对更多社交媒体平台的支持以进行分享

📄 许可证

MIT 许可证

---

<div align="center"> <p>由 🧠 AI 和人类协作构建</p> <p>由 Cursor + Claude 3.7 Sonnet 提供支持</p> </div>