Plex MCP Server

🚀 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

配置

1. 获取你的 Plex 令牌（详见 下方说明）
2. 创建环境文件：

# 复制示例环境文件
cp .env.example .env

# 编辑文件并填入你的信息
PLEX_URL=http://localhost:32400
PLEX_TOKEN=your_plex_token_here

3. 配置你的 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 媒体库"

高级用法

你可以根据具体需求，灵活组合不同的查询条件，以获取更精准的信息。例如，结合时间范围和媒体类型进行查询：

"过去一周我观看的动作电影有哪些？"

📚 详细文档

🛠️ 可用函数

🔑 获取你的 Plex 令牌

1. 在浏览器中打开 Plex 网页应用
2. 导航至设置 → 账户 → 隐私
3. 点击底部的“显示高级选项”
4. 复制你的 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

🤝 贡献代码

欢迎贡献代码！请随时提交拉取请求。对于重大更改，请先打开一个问题，讨论你想要进行的更改。

开发指南

1. ** Fork 仓库**
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开拉取请求

🐛 故障排除

常见问题

• 连接被拒绝：
  • 验证你的 Plex 服务器是否正在运行
  • 检查 .env 文件中的 PLEX_URL
  • 确保端口（通常为 32400）正确
• 身份验证错误：
  • 验证你的 Plex 令牌是否正确
  • 检查 Plex 设置中的令牌权限
  • 确保令牌未过期
• 空响应：
  • 某些功能需要 Plex Pass
  • 检查你的媒体库是否可访问
  • 验证媒体是否已扫描且可用
• MCP 客户端问题：
  • 确保 build/index.js 的路径正确
  • 检查 Node.js 是否在系统路径中
  • 验证客户端配置中是否设置了环境变量

获取帮助

• 📝 打开一个问题
• 💬 查看现有的 讨论
• 📖 查看 MCP 文档

📋 要求

• Node.js 18.0.0 或更高版本
• Plex 媒体服务器（任意较新版本）
• MCP 服务器和 Plex 服务器之间的网络访问权限
• 具有适当权限的有效 Plex 令牌

🔒 安全注意事项

• 妥善保管你的 Plex 令牌 - 切勿将其提交到版本控制系统
• 使用环境变量 存储敏感配置信息
• 在受信任的网络上运行 - 该服务器直接与 Plex 进行通信
• 定期轮换令牌 - 考虑定期刷新令牌

🔧 技术细节

项目依赖

本项目基于 Node.js 和 TypeScript 构建，使用了一系列开源库和工具。具体依赖信息可查看 package.json 文件。

实现原理

该 MCP 服务器通过与 Plex 媒体服务器进行交互，将 Plex 媒体库转换为可被 AI 助手查询的数据库。它接收来自 AI 助手的自然语言查询，解析查询意图，并根据查询内容从 Plex 媒体服务器中获取相应的数据。

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

• Anthropic 提供了模型上下文协议
• Plex 提供了出色的媒体服务器
• Tautulli 提供了分析灵感
• 开源社区提供了各种库和工具

🔗 相关项目

• 模型上下文协议 - 本服务器实现的标准
• Claude Desktop - 流行的 MCP 客户端
• Tautulli - Plex 监控和分析工具
• PlexAPI - Python Plex API 库

为 Plex 和 AI 社区用心打造 ❤️