Plex MCP 服务器

一个强大的模型-控制器-协议服务器，用于与 Plex 媒体服务器交互，提供基于标准化 JSON 的接口，适用于自动化、脚本编写和其他工具的集成。

概述

Plex MCP 服务器在 Plex 媒体服务器 API 上创建了一个统一的 API 层，提供：

• 兼容自动化工具、AI 系统和其他集成的标准化 JSON 响应
• 多种传输方法（标准输入输出和服务器发送事件）以实现灵活的集成选项
• 丰富的命令集，用于管理库、集合、播放列表、媒体、用户等
• 具有一致响应格式的错误处理
• 与自动化平台（如 n8n）和自定义脚本的简单集成

需求

• Python 3.8+
• 具有有效认证令牌的 Plex 媒体服务器
• 对 Plex 服务器的访问权限（本地或远程）

安装

1. 克隆此仓库
2. 安装所需依赖项：

   pip install -r requirements.txt
   

3. 根据 .env.example 创建 .env 文件：

   cp .env.example .env
   

4. 在 .env 文件中添加您的 Plex 服务器 URL 和令牌：

   PLEX_URL=http://your-plex-server:32400
   PLEX_TOKEN=your-plex-token
   

使用

该服务器可以在两种传输模式下运行：标准输入输出（stdio）或服务器发送事件（SSE）。每种模式都适合不同的集成场景。

使用标准输入输出传输运行

标准输入输出传输非常适合直接与 Claude Desktop 或 Cursor 等应用程序集成。它通过标准输入接受命令，并以 JSON 格式输出结果到标准输出。

基本命令行使用：

python3 -m plex_mcp

或者

python3 plex_mcp_server.py --transport stdio

Claude Desktop/Cursor 配置示例

将以下配置添加到您的应用程序设置中：

{
  "plex": {
    "command": "python",
    "args": [
      "C://Users//User//Documents//plex-mcp-server//plex_mcp_server.py",
      "--transport=stdio"
    ],
    "env": {
      "PLEX_URL":"http://localhost:32400",
      "PLEX_TOKEN":"av3khi56h634v3",
      "PLEX_USERNAME":"Administrator"
    }
  }
}

使用服务器发送事件传输运行

服务器发送事件（SSE）传输提供了基于 Web 的接口，适用于与 Web 应用程序和服务集成。

启动服务器：

python3 plex_mcp_server.py --transport sse --host 0.0.0.0 --port 3001

默认选项：

• 主机：0.0.0.0（从任何网络接口均可访问）
• 端口：3001
• SSE 终端点：/sse
• 消息终端点：/messages/

SSE 客户端配置示例

当服务器处于 SSE 模式时，配置您的客户端连接使用：

{
  "plex": {
    "url": "http://localhost:3001/sse"
  }
}

使用 SSE，您可以通过支持 SSE 连接的 Web 应用程序或工具连接到服务器。

命令模块

库模块

• 列出库
• 获取库统计信息
• 刷新库
• 扫描新内容
• 获取库详细信息
• 获取最近添加的内容
• 获取库内容

媒体模块

• 搜索媒体
• 获取详细媒体信息
• 编辑媒体元数据
• 删除媒体
• 获取和设置艺术作品
• 列出可用的艺术作品

播放列表模块

• 列出播放列表
• 获取播放列表内容
• 创建播放列表
• 删除播放列表
• 向播放列表添加项目
• 从播放列表移除项目
• 编辑播放列表
• 上传自定义海报图像
• 将播放列表复制给其他用户

集合模块

• 列出集合
• 创建集合
• 向集合添加项目
• 从集合移除项目
• 编辑集合

用户模块

• 搜索用户
• 获取用户信息
• 获取用户的即将观看内容
• 获取用户观看历史

会话模块

• 获取活动会话
• 获取媒体播放历史

服务器模块

• 获取 Plex 服务器日志
• 获取服务器信息
• 获取带宽统计信息
• 获取当前资源使用情况
• 获取并运行 Butler 任务
• 获取服务器警报

客户端模块

• 列出客户端
• 获取客户端详细信息
• 获取客户端时间线
• 获取活动客户端
• 开始媒体播放
• 控制播放（播放、暂停等）
• 导航客户端界面
• 设置音频/字幕流

注意： 客户端模块的功能目前有限且未完全实现。某些功能可能无法按预期工作或不完整。

响应格式

所有命令返回标准化的 JSON 响应，以最大限度地兼容各种工具、自动化平台和 AI 系统。这种一致的结构使得编程处理响应变得容易。

对于成功的操作，响应通常包括：

{
  "success_field": true,
  "relevant_data": "value",
  "additional_info": {}
}

对于错误，响应格式如下：

{
  "error": "描述出现问题的错误消息"
}

对于多个匹配项（按标题搜索时），结果作为包含标识信息的对象数组返回：

[
  {
    "title": "项目标题",
    "id": 12345,
    "type": "电影",
    "year": 2023
  },
  {
    "title": "另一个项目",
    "id": 67890,
    "type": "剧集",
    "year": 2022
  }
]

调试

为了开发和调试，您可以使用随附的 watcher.py 脚本，该脚本监视更改并自动重启服务器。

许可证

[在此处包含您的许可证信息]