内容
# Plex MCP 服务器
一款提供编程接口访问 Plex 媒体服务器功能的模型上下文协议（MCP）服务器。该服务器将 Plex 广泛的媒体管理、播放和库功能作为 MCP 工具暴露出来，可供 AI 助手和其他 MCP 客户端使用。
## 功能特点
- **媒体库管理**：浏览媒体库、获取媒体元数据、管理收藏
- **搜索**：跨所有媒体库或特定部分搜索
- **播放控制**：查看活动会话、更新播放时间线
- **用户观看历史**：跟踪用户观看模式、分析观看统计
- **个性化推荐**：根据用户偏好构建推荐系统
- **播放列表**：创建、管理、交互播放列表
- **内容发现**：获取推荐、中心、最近添加的内容、继续观看
- **观看状态**：标记项目为已观看/未观看、评分
- **Docker 支持**：使用 Docker 和 Portainer 轻松部署
- **强大的错误处理**：具有有意义的错误消息的全面错误处理
- **类型安全**：具有严格类型检查的完整 TypeScript 实现
## 前置条件
- Node.js 18.0.0 或更高版本（用于本地安装）
- 或 Docker（用于容器化部署）
- 运行中的 Plex 媒体服务器
- Plex 身份验证令牌
## 安装
### 选项 1：Docker 部署（推荐）
使用 Docker 和 Portainer 部署以实现轻松管理：
**参见 [PORTAINER_DEPLOYMENT.md](PORTAINER_DEPLOYMENT.md) 获取详细的 Portainer 部署说明。**
使用 Docker Compose 快速启动：
```bash
# 克隆仓库
git clone https://github.com/Jamdries/plex-mcp
cd plex-mcp
# 复制环境模板
cp .env.example .env
# 使用您的 Plex 凭证编辑 .env
nano .env
# 使用 Docker Compose 构建并运行
docker-compose up -d
```
### 选项 2：本地安装
1. 克隆仓库：
```bash
git clone <仓库网址>
cd plex-mcp-server
```
2. 安装依赖项：
```bash
npm install
```
3. 构建项目：
```bash
npm run build
```
## 配置
服务器可以使用环境变量或配置文件进行配置。
### 选项 1：环境变量
在项目根目录中创建 `.env` 文件：
```env
PLEX_SERVER_URL=https://192-168-1-100.abc123def456.plex.direct:32400
PLEX_TOKEN=您的_plex_token_在此
PLEX_TIMEOUT=30000
PLEX_VALIDATE_SSL=true
```
### 选项 2：配置文件
创建 `plex-config.json` 文件：
```json
{
"plexServerUrl": "https://192-168-1-100.abc123def456.plex.direct:32400",
"plexToken": "您的_plex_token_在此",
"timeout": 30000,
"validateSSL": true
}
```
### 获取 Plex 令牌
要获取您的 Plex 身份验证令牌：
1. 登录到 [Plex 网页应用](https://app.plex.tv/)
2. 打开任意媒体项目
3. 点击三个点菜单 → “获取信息”
4. 点击“查看 XML”
5. 在 URL 中查找 `X-Plex-Token`
有关更多详细信息，请参阅 [官方 Plex 文档](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/).
### 查找 Plex 服务器网址
您的 Plex 服务器网址通常遵循以下模式：
```
https://{IP-description}.{identifier}.plex.direct:{port}
```
示例：`https://192-168-1-100.abc123def456.plex.direct:32400`
您可以在以下位置找到它：
- Plex 网页应用 → 设置 → 网络 → 服务器网址
- 或使用 `http://localhost:32400` 如果在同一台机器上运行
## 用法
### 运行服务器
```bash
npm start
```
或在开发环境中使用自动重新加载：
```bash
npm run dev
```
### 与 Claude Desktop 一起使用
将以下内容添加到您的 Claude Desktop 配置文件中：
**macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**：`%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"plex": {
"command": "node",
"args": ["/path/to/plex-mcp-server/dist/index.js"],
"env": {
"PLEX_SERVER_URL": "https://192-168-1-100.abc123def456.plex.direct:32400",
"PLEX_TOKEN": "您的_plex_token_在此"
}
}
}
}
```
## 可用工具
### 服务器信息
- **get_server_info**：获取 Plex 媒体服务器信息和身份
### 媒体库管理
- **list_libraries**：获取所有媒体库部分
- **get_library_items**：获取媒体库部分中的所有项目
- **get_item_metadata**：获取特定项目的详细元数据
### 搜索
- **search_media**：跨所有媒体库搜索
- **search_library**：在特定媒体库部分中搜索
### 播放和会话
- **get_sessions**：获取活动播放会话
- **update_timeline**：更新媒体项目的播放位置/状态
- **get_recently_added**：获取最近添加的媒体项目
### 继续观看
- **get_on_deck**：获取正在等待观看的项目
### 播放列表
- **list_playlists**：获取所有播放列表
- **get_playlist_items**：获取播放列表中的项目
- **create_playlist**：创建新播放列表
- **add_to_playlist**：将项目添加到播放列表
### 收藏
- **list_collections**：获取媒体库部分中的收藏
- **get_collection_items**：获取收藏中的项目
### 观看状态
- **mark_watched**：标记项目为已观看
- **mark_unwatched**：标记项目为未观看
### 评分
- **rate_item**：对媒体项目进行评分（0-10）
### 内容发现
- **get_hubs**：获取所有内容中心（推荐）
### 用户管理与观看历史
- **get_accounts**：获取服务器上的所有用户账户
- **get_session_history**：获取完整的观看历史，附带可选过滤器（accountID、librarySectionID、ratingKey、mindate）
- **get_user_watch_history**：获取特定用户的观看历史
- **get_user_watch_statistics**：获取用户的详细观看统计和偏好（包括最常观看的项目、最近的观看历史和总观看次数）
## 示例用法
一旦使用 Claude Desktop 等 MCP 客户端配置完成，您就可以使用自然语言与 Plex 服务器交互：
**常规查询：**
- “我的 Plex 媒体库中有哪些电影？”
- “在我的 Plex 服务器上搜索‘The Matrix’”
- “我目前正在 Plex 上观看什么？”
- “显示我最近添加的内容”
- “创建一个名为‘Favorites’的播放列表”
- “标记第 5 集为已观看”
**用户观看历史和推荐：**
- “谁是我的 Plex 服务器上的所有用户？”
- “用户 ID 12345 最近在观看什么？”
- “显示用户 John 最常观看的节目”
- “用户 Jane 的观看偏好是什么？”
- “根据用户 Bob 的观看习惯推荐类似的节目”
- “获取所有用户的观看统计数据”
## 开发
### 项目结构
```
plex-mcp-server/
├── src/
│ ├── index.ts # 主要的 MCP 服务器入口点
│ ├── plex-client.ts # Plex API 客户端包装器
│ ├── types.ts # TypeScript 类型定义
│ └── config.ts # 配置管理
├── openapi.json # OpenAPI 规范（参考）
├── package.json
├── tsconfig.json
└── README.md
```
### 构建命令
- `npm run build` - 将 TypeScript 构建为 JavaScript
- `npm run watch` - 监视模式，用于开发
- `npm run dev` - 在开发模式下使用 tsx 运行
- `npm start` - 运行已构建的服务器
## 错误处理
服务器包含针对以下情况的全面错误处理：
- 网络错误（超时、连接被拒绝）
- 身份验证错误（401、403）
- 未找到错误（404）
- 服务器错误（500+）
- 速率限制（429）
- 无效参数
所有错误都返回带有有意义的错误消息，以帮助诊断问题。
## 安全考虑
- 安全存储您的 Plex 令牌
- 使用环境变量或安全配置文件
- 不要将令牌提交到版本控制
- 在生产环境中考虑使用 SSL 验证（`validateSSL: true`）
- 使用 Plex 内置的安全功能限制服务器访问
## 故障排除
### 无法连接到 Plex 服务器
- 验证服务器 URL 是否正确
- 检查 Plex 服务器是否正在运行
- 确保到服务器的网络连接
- 验证防火墙规则是否允许连接
### 身份验证失败
- 检查您的 Plex 令牌是否有效
- 确保令牌具有适当的权限
- 尝试从 Plex 网页应用重新生成令牌
### SSL/TLS 错误
- 如果使用自签名证书，请设置 `validateSSL: false`
- 对于生产环境，请使用正确的 SSL 证书
## API 覆盖
此 MCP 服务器实现了最常用的 Plex API 端点：
- **服务器信息**：身份、状态、功能
- **媒体库管理**：部分、项目、元数据
- **搜索**：全局和特定于部分的搜索
- **播放**：会话、时间线更新
- **播放列表**：CRUD 操作
- **收藏**：浏览和管理收藏
- **观看状态**：记为已观看/未观看、评分
- **内容发现**：中心、推荐
有关完整的 Plex API 规范，请参见 `openapi.json`。
## 许可证
Apache 2.0
## 资源
- [模型上下文协议文档](https://modelcontextprotocol.io/)
- [Plex API 文档](https://www.plexopenapispec.com/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
## 贡献
欢迎贡献！请随意提交问题或拉取请求。
## 支持
有关问题和疑问：
- 查看 [故障排除部分](#troubleshooting)
- 查看 [Plex API 文档](https://www.plexopenapispec.com/)
- 在 GitHub 上提交问题
