🚀 Plex MCP 服务器
Plex MCP 服务器是一款基于 模型上下文协议（Model Context Protocol，MCP） 的服务器，它能让 AI 助手全面访问你的 Plex 媒体服务器。你可以通过自然语言交互来查询媒体库、获取观看统计数据，以及管理媒体资源。
🚀 快速开始
前提条件
- Node.js 18 及以上版本
- Plex 媒体服务器（任意较新版本）
- Plex 令牌（获取 Plex 令牌的方法）
- 支持 MCP 的客户端（如 Claude Desktop 等）
安装
# 克隆仓库
git clone https://github.com/niavasha/plex-mcp-server.git
cd plex-mcp-server
# 安装依赖
npm install
# 构建项目
npm run build
配置
- 获取你的 Plex 令牌（详见 下方说明）
- 创建环境文件：
# 复制示例环境文件
cp .env.example .env
# 编辑文件并填入你的信息
PLEX_URL=http://localhost:32400
PLEX_TOKEN=your_plex_token_here
- 配置你的 MCP 客户端： 在 MCP 客户端配置中添加以下内容（例如 Claude Desktop）：
{
"mcpServers": {
"plex": {
"command": "node",
"args": ["/path/to/plex-mcp-server/build/index.js"],
"env": {
"PLEX_URL": "http://localhost:32400",
"PLEX_TOKEN": "your_plex_token_here"
}
}
}
}
使用
配置完成后，你可以向 AI 助手提出以下问题：
🎬 "我上周看了哪些电影？"
📺 "给我展示本月最受欢迎的电视剧"
📊 "提供过去 30 天的观看统计数据"
🔍 "在我的媒体库中搜索克里斯托弗·诺兰的电影"
▶️ "我的继续观看列表中有什么？"
📚 "列出我所有的 Plex 媒体库"
✨ 主要特性
📚 媒体库管理
- 浏览所有 Plex 媒体库
- 在电影、电视剧、音乐等媒体类型中进行搜索
- 获取任何媒体项的详细元数据
📊 类 Tautulli 分析
- 全面的观看统计数据
- 用户活动跟踪
- 热门内容分析
- 带有进度跟踪的观看历史记录
- 媒体库使用指标
🎯 智能查询
- 最近观看的内容
- 已完整观看的电影/电视剧
- 继续观看列表（待播）
- 最近添加的媒体
📦 安装指南
安装步骤
# 克隆仓库
git clone https://github.com/niavasha/plex-mcp-server.git
cd plex-mcp-server
# 安装依赖
npm install
# 构建项目
npm run build
💻 使用示例
基础用法
配置完成后，你可以向 AI 助手提出如下自然语言问题：
🎬 "我上周看了哪些电影？"
📺 "给我展示本月最受欢迎的电视剧"
📊 "提供过去 30 天的观看统计数据"
🔍 "在我的媒体库中搜索克里斯托弗·诺兰的电影"
▶️ "我的继续观看列表中有什么？"
📚 "列出我所有的 Plex 媒体库"
高级用法
你可以根据具体需求，灵活组合不同的查询条件，以获取更精准的信息。例如，结合时间范围和媒体类型进行查询：
"过去一周我观看的动作电影有哪些？"
📚 详细文档
🛠️ 可用函数
| 属性 | 详情 |
|---|---|
get_libraries |
列出所有 Plex 媒体库，示例用法："我有哪些媒体库？" |
search_media |
在所有媒体中进行搜索，示例用法："查找有汤姆·汉克斯参演的电影" |
get_recently_added |
获取最近添加的内容，示例用法："我的服务器上有什么新内容？" |
get_on_deck |
获取继续观看列表，示例用法："我应该继续观看什么？" |
get_media_details |
获取媒体详细信息，示例用法："给我介绍一下《黑客帝国》" |
get_recently_watched |
获取最近观看的内容，示例用法："我昨天看了什么？" |
get_fully_watched |
获取已完整观看的内容，示例用法："给我展示所有已观看的电影" |
get_watch_history |
获取详细的观看记录，示例用法："展示我的观看历史" |
get_watch_stats |
获取观看分析数据，示例用法："我的观看统计数据" |
get_user_stats |
获取用户活动数据，示例用法："谁观看的内容最多？" |
get_library_stats |
获取媒体库信息，示例用法："给我介绍一下我的电影库" |
get_popular_content |
获取最受欢迎的媒体，示例用法："我的服务器上什么内容最热门？" |
🔑 获取你的 Plex 令牌
- 在浏览器中打开 Plex 网页应用
- 导航至设置 → 账户 → 隐私
- 点击底部的“显示高级选项”
- 复制你的 Plex 令牌
另一种方法：
- 访问：
http://YOUR_PLEX_IP:32400/web/index.html#!/settings/account - 查找“Plex 令牌”字段
📁 项目结构
plex-mcp-server/
├── src/
│ └── index.ts # 主要的 MCP 服务器实现
├── build/ # 编译后的 JavaScript 输出
├── package.json # Node.js 依赖和脚本
├── tsconfig.json # TypeScript 配置
├── .env.example # 环境变量模板
├── README.md # 本文件
└── LICENSE # MIT 许可证
🔧 开发
脚本
# 开发模式，支持自动重新加载
npm run dev
# 为生产环境构建
npm run build
# 启动生产服务器
npm start
# 运行测试（如果已实现）
npm test
从源代码构建
# 克隆并设置项目
git clone https://github.com/niavasha/plex-mcp-server.git
cd plex-mcp-server
npm install
# 开发模式
npm run dev
🤝 贡献代码
欢迎贡献代码！请随时提交拉取请求。对于重大更改，请先打开一个问题，讨论你想要进行的更改。
开发指南
- ** Fork 仓库**
- 创建功能分支 (
git checkout -b feature/amazing-feature) - 提交更改 (
git commit -m 'Add amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 打开拉取请求
🐛 故障排除
常见问题
- 连接被拒绝：
- 验证你的 Plex 服务器是否正在运行
- 检查
.env文件中的PLEX_URL - 确保端口（通常为 32400）正确
- 身份验证错误：
- 验证你的 Plex 令牌是否正确
- 检查 Plex 设置中的令牌权限
- 确保令牌未过期
- 空响应：
- 某些功能需要 Plex Pass
- 检查你的媒体库是否可访问
- 验证媒体是否已扫描且可用
- MCP 客户端问题：
- 确保
build/index.js的路径正确 - 检查 Node.js 是否在系统路径中
- 验证客户端配置中是否设置了环境变量
- 确保
获取帮助
📋 要求
- Node.js 18.0.0 或更高版本
- Plex 媒体服务器（任意较新版本）
- MCP 服务器和 Plex 服务器之间的网络访问权限
- 具有适当权限的有效 Plex 令牌
🔒 安全注意事项
- 妥善保管你的 Plex 令牌 - 切勿将其提交到版本控制系统
- 使用环境变量 存储敏感配置信息
- 在受信任的网络上运行 - 该服务器直接与 Plex 进行通信
- 定期轮换令牌 - 考虑定期刷新令牌
🔧 技术细节
项目依赖
本项目基于 Node.js 和 TypeScript 构建，使用了一系列开源库和工具。具体依赖信息可查看 package.json 文件。
实现原理
该 MCP 服务器通过与 Plex 媒体服务器进行交互，将 Plex 媒体库转换为可被 AI 助手查询的数据库。它接收来自 AI 助手的自然语言查询，解析查询意图，并根据查询内容从 Plex 媒体服务器中获取相应的数据。
📄 许可证
本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。
🙏 致谢
🔗 相关项目
- 模型上下文协议 - 本服务器实现的标准
- Claude Desktop - 流行的 MCP 客户端
- Tautulli - Plex 监控和分析工具
- PlexAPI - Python Plex API 库
为 Plex 和 AI 社区用心打造 ❤️