AI导哈

Plex媒体服务器API接口

Plex MCP Server是一个为Plex Media Server提供标准化JSON接口的模型-控制器-协议服务器，支持自动化、脚本编写和与其他工具的集成。

  • by Jamdries
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Jamdries/plex-mcp-server

使用说明

Plex MCP服务器

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

概述

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

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

需求

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

安装

  1. 克隆此存储库
  2. 安装所需的依赖项：
    pip install -r requirements.txt
  3. 创建一个 .env 文件基于 .env.example:
    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桌面/光标配置示例

将此配置添加到应用程序的设置中：

{
  "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

默认选项：

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

SSE客户端配置示例

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

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

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

只读模式🔒

默认情况下，服务器以只读模式运行 保护您的Plex服务器免受意外修改。这在以下情况下特别有用：

  • 首次测试服务器
  • 与AI代理或不受信任的应用程序集成
  • 提供对Plex信息的安全访问，没有修改风险
  • 在需要控制更改的生产环境中运行

运作原理

启用只读模式时，所有写入操作都会被阻止：

  • ❌ 库扫描和刷新
  • ❌ 媒体编辑和删除
  • ❌ 播放列表/收藏集的创建和修改
  • ❌ 播放控制
  • ❌ 服务器维护任务
  • ✅ 所有读取操作（搜索、列出、查看）仍然可用

如果尝试写入操作，您将收到错误：

{
  "error": "Operation 'media_delete' is not allowed in read-only mode. Set READ_ONLY_MODE=false in your environment to enable write operations."
}

启用写入操作

要允许修改您的Plex服务器，请设置 READ_ONLY_MODE 环境变量 false:

选项1：环境变量

export READ_ONLY_MODE=false
python3 plex_mcp_server.py

选项2:.env文件 添加到您的 .env 文件：

READ_ONLY_MODE=false

选项3：Docker编写 在你的 docker-compose.yml:

environment:
  - READ_ONLY_MODE=false

选项4:Docker运行

docker run -e READ_ONLY_MODE=false plex-mcp-server

安全建议

  • ⚠️ 仅在必要时禁用只读模式
  • 🔐 为AI代理和自动化系统保持启用状态
  • 📝 对监控和报告工具使用只读模式
  • 🎯 仅对受信任的管理工具禁用

命令模块

库模块

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

媒体模块

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

播放列表模块

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

采集模块

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

用户模块

  • 搜索用户
  • 获取用户信息
  • 获取用户的甲板内容
  • 获取用户观看历史记录

会话模块

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

服务器模块

  • 获取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 监视更改并自动重新启动服务器的脚本。

许可证

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

相关 MCP