AI导哈

媒体管理协议服务器

Plex MCP Server是一个提供程序化访问Plex媒体服务器功能的模型上下文协议（MCP）服务器，适用于AI助手和其他MCP客户端。

  • by Jamdries
  • JavaScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Jamdries/plex-mcp

使用说明

Plex MCP服务器

一种模型上下文协议（MCP）服务器，提供对Plex媒体服务器功能的编程访问。此服务器将Plex的广泛媒体管理、播放和库功能作为MCP工具公开，可供AI助手和其他MCP客户端使用。

特性

  • 图书馆管理：浏览库、获取媒体元数据和管理收藏
  • 搜索：搜索所有库或特定部分
  • 回放控制：查看活动会话并更新播放时间线
  • 用户观看历史记录：跟踪用户观看模式并分析手表统计数据
  • 个性化推荐：根据用户偏好构建推荐系统
  • 播放列表：创建、管理播放列表并与之交互
  • 内容发现：获取推荐、中心、最近添加的内容，并继续观看
  • 观察状态：将项目标记为已观看/未观看，并对内容进行评分
  • Docker支持：使用Docker和Portainer轻松部署
  • 稳健的错误处理：全面的错误处理，带有有意义的错误消息
  • 类型安全：具有严格类型检查的完整TypeScript实现

先决条件

  • Node.js 18.0.0或更高版本（用于本地安装）
  • OR Docker（用于容器化部署）
  • 正在运行的Plex媒体服务器
  • Plex身份验证令牌

安装

选项1:Docker部署（推荐）

使用Docker和Portainer进行部署，以便于管理：

看 港口_港口.md 有关Portainer部署的详细说明。

Docker Compose快速入门：

# Clone the repository
git clone https://github.com/Jamdries/plex-mcp
cd plex-mcp

# Copy environment template
cp .env.example .env

# Edit .env with your Plex credentials
nano .env

# Build and run with Docker Compose
docker-compose up -d

选项2：本地安装

  1. 克隆存储库：
git clone <repository-url>
cd plex-mcp-server
  1. 安装依赖项：
npm install
  1. 构建项目：
npm run build

配置

服务器可以使用环境变量或配置文件进行配置。

选项1：环境变量

创建一个 .env 项目根目录中的文件：

PLEX_SERVER_URL=https://192-168-1-100.abc123def456.plex.direct:32400
PLEX_TOKEN=your_plex_token_here
PLEX_TIMEOUT=30000
PLEX_VALIDATE_SSL=true

选项2：配置文件

创建一个 plex-config.json 文件：

{
  "plexServerUrl": "https://192-168-1-100.abc123def456.plex.direct:32400",
  "plexToken": "your_plex_token_here",
  "timeout": 30000,
  "validateSSL": true
}

获取您的Plex令牌

要获取Plex身份验证令牌，请执行以下操作：

  1. 登录到…… Plex Web应用程序
  2. 打开任何媒体项目
  3. 点击三点菜单→ “获取信息”
  4. 点击“查看XML”
  5. 寻找 X-Plex-Token 在URL中

有关更多详细信息，请参阅 Plex官方文档.

查找您的Plex服务器URL

您的Plex服务器URL通常遵循以下模式：

https://{IP-description}.{identifier}.plex.direct:{port}

例子： https://192-168-1-100.abc123def456.plex.direct:32400

您可以在以下网址找到：

  • Plex Web应用程序→ 设置→ 网络→ 服务器URL
  • 或使用 http://localhost:32400 如果在同一台机器上运行

用法

运行服务器

npm start

或者用于自动重新加载的开发：

npm run dev

与Claude Desktop一起使用

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.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": "your_plex_token_here"
      }
    }
  }
}

可用工具

服务器信息

  • get_server_info：获取Plex媒体服务器信息和身份

图书馆管理

  • list_librarys：获取所有库部分
  • get_library_items：获取库部分中的所有项目
  • get_item_metadata：获取特定项目的详细元数据

搜索

  • 搜索媒体：搜索所有库
  • 搜索库：在特定库部分内搜索

回放和会话

  • get_sessions：获取活动播放会话
  • update_timeline：更新媒体项目的播放位置/状态
  • 获取最近添加的内容：获取最近添加的媒体项目

继续观看

  • get_on_deck：登上甲板物品（继续观看）

播放列表

  • list_playlists：获取所有播放列表
  • get_playlist_items：获取播放列表中的项目
  • 创建播放列表：创建新的播放列表
  • add_to_playlist：将项目添加到播放列表

集合

  • list_collections：在图书馆部分获取馆藏
  • get_collection_mitems：获取收藏中的项目

观察状态

  • 标记_已修补：将项目标记为已关注（滚动）
  • mark_unwatched：将某个项目标记为不受监视（不可拆卸）

评分

  • 费率_项目：对媒体项目进行评分（0-10）

内容发现

  • get_hubs：获取所有内容中心（推荐）

用户管理和观看历史记录

  • 获取计数：获取服务器上的所有用户帐户
  • get_session历史记录：使用可选过滤器（accountID、librarySectionID、ratingKey、mindate）获取完整的手表历史记录
  • get_user_watch_history：获取特定用户的手表历史记录
  • get_user_watch_统计数据：获取用户的详细手表统计数据和偏好（包括观看次数最多的项目、最近的历史记录和总手表数）

示例用法

一旦配置了像Claude Desktop这样的MCP客户端，您就可以使用自然语言与Plex服务器进行交互：

一般查询：

  • “我的Plex库中有哪些电影？”
  • “在我的Plex服务器中搜索‘The Matrix’”
  • “我目前在Plex上看什么？”
  • “显示最近添加的内容”
  • “创建一个名为“收藏夹”的播放列表”
  • “标记观看的第5集”

用户观看历史记录和建议：

  • “我的Plex服务器上的所有用户都是谁？”
  • “用户ID 12345一直在看什么？”
  • “显示用户John观看次数最多的节目”
  • “用户Jane的观看偏好是什么？”
  • “根据用户Bob观看的内容推荐类似的节目”
  • “获取所有用户的手表统计信息”

发展

项目结构

plex-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server entry point
│   ├── plex-client.ts        # Plex API client wrapper
│   ├── types.ts              # TypeScript type definitions
│   └── config.ts             # Configuration management
├── openapi.json              # OpenAPI specification (reference)
├── package.json
├── tsconfig.json
└── README.md

构建命令

  • npm run build -将TypeScript构建为JavaScript
  • npm run watch -开发观看模式
  • npm run dev -使用tsx在开发模式下运行
  • npm start -运行内置服务器

错误处理

该服务器包括全面的错误处理功能，用于：

  • 网络错误（超时、连接被拒绝）
  • 身份验证错误（401403）
  • 未发现错误（404）
  • 服务器错误（500+）
  • 速率限制（429）
  • 无效参数

所有错误都会返回有意义的错误消息，以帮助诊断问题。

安全考虑

  • 安全地存储您的Plex令牌
  • 使用环境变量或安全配置文件
  • 不要将令牌提交到版本控制
  • 考虑在生产中使用SSL验证(validateSSL: true)
  • 使用Plex的内置安全功能限制服务器访问

故障排除

无法连接到Plex服务器

  • 验证服务器URL是否正确
  • 检查Plex服务器是否正在运行
  • 确保与服务器的网络连接
  • 验证防火墙规则是否允许连接

认证失败

  • 检查您的Plex令牌是否有效
  • 确保令牌具有适当的权限
  • 尝试从Plex Web App重新生成令牌

SSL/TLS错误

  • 如果使用自签名证书，请设置 validateSSL: false
  • 对于生产，使用适当的SSL证书

API覆盖范围

此MCP服务器实现了最常用的Plex API端点：

  • 服务器信息：身份、地位、能力
  • 图书馆管理：章节、项目、元数据
  • 搜索：全局和特定部门搜索
  • 回放：会议、时间表更新
  • 播放列表：CRUD操作
  • 集合：浏览和管理收藏
  • 观察状态：可拆卸/不可拆卸，额定值
  • 内容发现：中心、建议

有关完整的Plex API规范，请参阅 openapi.json.

许可证

Apache 2.0

资源

贡献

欢迎投稿！请随时提交问题或拉取请求。

支持

对于问题和疑问：

相关 MCP