金大哥 - plex-mcp-server MCP 详情

article

README

🚀 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 是否在系统路径中
- 验证客户端配置中是否设置了环境变量

获取帮助

📝 打开一个问题
💬 查看现有的讨论
📖 查看 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 社区用心打造 ❤️

plex-mcp-server