Plex MCP 服务器

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

概述

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

• 标准化的 JSON 响应，与自动化工具、AI 系统和其他集成兼容
• 多种传输方法（stdio 和 SSE），提供灵活的集成选项
• 丰富的命令集，用于管理库、收藏集、播放列表、媒体、用户等
• 错误处理，具有一致的响应格式
• 易于集成，可与自动化平台（如 n8n）和自定义脚本集成

要求

• Python 3.8+
• 具有有效身份验证令牌的 Plex Media Server
• 访问 Plex 服务器（本地或远程）

安装

1. 克隆此存储库
2. 安装所需的依赖项：

   pip install -r requirements.txt
   

3. 基于 .env.example 创建一个 .env 文件：

   cp .env.example .env
   

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

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

用法

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

使用 stdio 传输运行

stdio 传输非常适合与 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 传输运行

服务器发送事件 (SSE) 传输提供了一个基于 Web 的界面，用于与 Web 应用程序和服务集成。

启动服务器：

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

默认选项：

• Host: 0.0.0.0 (可从任何网络接口访问)
• Port: 3001
• SSE endpoint: /sse
• Message endpoint: /messages/

SSE 客户端的配置示例

当服务器在 SSE 模式下运行时，配置您的客户端以使用以下方式连接：

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

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

命令模块

库模块

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

媒体模块

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

播放列表模块

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

收藏集模块

• 列出收藏集
• 创建收藏集
• 将项目添加到收藏集
• 从收藏集中删除项目
• 编辑收藏集

用户模块

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

会话模块

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

服务器模块

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

客户端模块

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

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

响应格式

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

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

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

对于错误，响应格式为：

{
  "error": "Error message describing what went wrong"
}

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

[
  {
    "title": "Item Title",
    "id": 12345,
    "type": "movie",
    "year": 2023
  },
  {
    "title": "Another Item",
    "id": 67890,
    "type": "show",
    "year": 2022
  }
]

调试

对于开发和调试，您可以使用包含的 watcher.py 脚本，该脚本会监视更改并自动重启服务器。

许可证

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