使用说明

项目简介

Plex MCP Server 是一款基于 Model Context Protocol (MCP) 构建的服务器应用，旨在作为 Plex 媒体服务器的控制面板，允许 AI 助手等 MCP 客户端通过标准化的方式访问和操作您的 Plex 媒体库。它提供了一系列工具，使您能够使用 AI 助手来搜索媒体、控制播放、管理媒体库、查看服务器状态等。

主要功能点

全面的 Plex 库访问: 允许 AI 助手浏览和搜索您的 Plex 媒体库，包括电影、电视剧、音乐等。
媒体搜索和播放控制: 支持通过 AI 助手搜索指定的媒体，并在 Plex 客户端上开始播放。
媒体库和用户管理: 可以列出和刷新媒体库，查看用户活动会话，获取用户观看历史等。
元数据编辑: 允许修改媒体的标题、摘要、评分等元数据信息。
播放列表和合集管理: 支持创建、编辑和删除播放列表和合集。
服务器监控: 提供查看 Plex 服务器日志和活动会话的功能。

安装步骤

克隆仓库: 首先，将 GitHub 仓库 'plex-mcp-server' 克隆到您的本地计算机。

git clone https://github.com/vladimir-tutin/plex-mcp-server
cd plex-mcp-server

安装依赖: 使用 pip 安装项目所需的 Python 依赖包。

pip install -r requirements.txt

配置 Plex 连接:

方式一：使用 .env 文件 (推荐): 在项目根目录下创建 '.env' 文件，并填入您的 Plex 服务器 URL 和令牌 (Token)。

PLEX_URL=http://your-plex-server:32400  # 替换为您的 Plex 服务器地址
PLEX_TOKEN=your-plex-token           # 替换为您的 Plex 令牌

您可以在您的 Plex 服务器 Web 界面的 "设置" -> "账户" -> "令牌" 中找到或创建 Plex 令牌。

方式二：设置环境变量: 您可以直接在您的操作系统环境中设置 'PLEX_URL' 和 'PLEX_TOKEN' 环境变量。

export PLEX_URL=http://your-plex-server:32400  # Linux/macOS
export PLEX_TOKEN=your-plex-token

set PLEX_URL=http://your-plex-server:32400   # Windows 命令提示符
set PLEX_TOKEN=your-plex-token

$env:PLEX_URL="http://your-plex-server:32400" # Windows PowerShell
$env:PLEX_TOKEN="your-plex-token"

注意: 如果使用用户名和密码进行身份验证，请设置 'PLEX_USERNAME'、'PLEX_PASSWORD' 和 'PLEX_SERVER_NAME' 环境变量。

服务器配置 (MCP 客户端)

要将 Plex MCP Server 集成到 MCP 客户端（例如 Claude Desktop 或 Cursor），您需要配置客户端以连接到此服务器。以下是一个 JSON 格式的配置示例，您需要将其添加到 MCP 客户端的服务器配置中。

{
  "server name": "plex-server",
  "command": "python",
  "args": [
    "path/to/plex_mcp_server.py",  //  请替换为 plex_mcp_server.py 脚本的实际路径
    "--transport",
    "stdio"                        //  使用 stdio 传输模式，适用于本地客户端
  ],
  "env": {
    //  环境变量配置，通常情况下无需在此处重复配置，
    //  因为服务器程序会从系统环境变量或 .env 文件中读取
    // "PLEX_URL": "http://your-plex-server:32400",
    // "PLEX_TOKEN": "your-plex-token"
  }
}

配置参数说明:

server name: 服务器名称，您可以在 MCP 客户端中自定义，用于标识此 Plex MCP Server 连接，例如 "plex-server"。
command: 启动 Plex MCP Server 的命令，通常为 Python 解释器 'python'。
args: 传递给 'python' 命令的参数列表：
- '"path/to/plex_mcp_server.py"': 请务必替换为 您本地 'plex_mcp_server.py' 脚本的绝对路径。
- '"--transport"': 指定服务器使用的传输协议。
- '"stdio"': 使用标准输入输出流 (stdio) 作为传输协议。这是最常用的本地连接方式，适用于 MCP 客户端和服务器运行在同一台机器上的情况。如果您希望通过网络访问，可以考虑使用 'sse' 传输模式，并参考仓库文档配置 Web Server 模式。
env: 环境变量配置，用于传递 Plex 服务器的连接信息。通常情况下，您可以将 Plex 连接信息配置在服务器端的 '.env' 文件或系统环境变量中，因此此处可以留空或注释掉。如果您的 MCP 客户端有特殊的环境变量传递机制，您也可以在此处配置 'PLEX_URL' 和 'PLEX_TOKEN'。

重要提示:

请确保将 '"path/to/plex_mcp_server.py"' 替换为 'plex_mcp_server.py' 脚本在您计算机上的实际完整路径。
如果 MCP 客户端和 Plex MCP Server 运行在不同的机器上，您需要配置服务器以 'sse' 传输模式运行，并配置客户端连接到服务器的 SSE 端点。请参考仓库 README 文档中关于 "Web Server Mode" 的说明。

基本使用方法

启动服务器: 根据您的需求选择运行模式。
- 命令行模式 (默认): 在项目根目录下，运行以下命令启动服务器 (使用 stdio 传输)。
```
python plex_mcp_server.py
```
- Web 服务器模式 (SSE 传输): 如果您需要通过网络访问服务器，可以运行以下命令启动 Web 服务器模式 (使用 SSE 传输)。
```
python plex_mcp_server.py --transport sse --host 0.0.0.0 --port 8080
```
  服务器将在 'http://[host]:[port]' 启动，SSE 端点为 '/sse'。
在 MCP 客户端中使用: 启动 Plex MCP Server 后，在您的 MCP 客户端（如 Claude Desktop 或 Cursor）中，您应该能够看到 Plex 相关的工具或功能。具体使用方式取决于您的 MCP 客户端的界面和功能设计。通常，您可以通过输入自然语言指令或选择工具菜单来调用 Plex MCP Server 提供的功能，例如：
- "列出我的 Plex 媒体库"
- "搜索电影 '星际穿越'"
- "播放最近添加的电视剧"
- "获取电影 '泰坦尼克号' 的海报"
请参考您的 MCP 客户端的文档，了解如何使用集成的 MCP 服务器工具。

关键词