MCP 服务器

Trakt

wwiens

研究与数据

访问服务器

README

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

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

🖥️ 一个 AI 实验

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

🤖 什么是 MCP？

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

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

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

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

资源 (Resources)：AI 可以读取或写入的结构化数据源（例如 trakt://shows/trending）
工具 (Tools)：AI 可以调用以执行特定操作的函数（例如 fetch_trending_shows）
会话 (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 数据

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

🔄 一般功能

通过 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`	经过身份验证的用户观看的电影	电影标题、年份、上次观看日期、播放次数

🛠️ 可用工具

节目工具

# 获取热门节目，带有可选的 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="绝命毒师", 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="绝命毒师", limit=5)
# 然后使用 ID 进行签到
checkin_to_show(
    season=1, 
    episode=3, 
    show_id="1388",
    message="喜欢这个节目！"
)

# 方法 2：使用节目标题签到（更方便）
checkin_to_show(
    season=1, 
    episode=1,
    show_title="绝命毒师", 
    show_year=2008,  # 可选，但有助于提高准确性
    message="我就是那个敲门的人！",
    share_twitter=True,
    share_mastodon=False,
    share_tumblr=False
)

🔐 身份验证

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

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

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

🚀 设置

克隆此存储库

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
```

🧪 开发和测试

使用 MCP Inspector 进行测试

mcp dev server.py

在 Claude Desktop 中安装

mcp install server.py

📝 与 Claude 一起使用

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

"现在有哪些热门节目？"
"你能推荐一些本周流行的电影吗？"
"本月观看次数最多的节目是什么？"
"显示我观看过的节目"（需要身份验证）
"我上次观看的节目是什么？"（需要身份验证）
"显示我观看过的电影"（需要身份验证）
"我上次观看的电影是什么？"（需要身份验证）
"搜索像'绝命毒师'这样的节目"
"签到绝命毒师第 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>