Plex MCP 服务器

这是一个基于 Python 的 MCP 服务器，它与 Plex 媒体服务器 API 集成，用于搜索电影和管理播放列表。它使用 PlexAPI 库来无缝地与您的 Plex 服务器交互。

屏幕截图

以下是一些 Plex MCP 服务器工作方式的例子：

1. 按导演查找 Plex 库中的电影

通过指定导演的名字来搜索您 Plex 库中的电影。例如，搜索“Alfred Hitchcock”会返回库中他的电影列表。

2. 查找缺失的导演电影

识别特定导演在您的 Plex 库中缺失的电影。这有助于发现收藏中的空白。

3. 在您的 Plex 库中创建播放列表

使用搜索找到的电影在您的 Plex 库中创建一个新的播放列表。这使您可以高效地组织您的媒体库。

设置

先决条件

• Python 3.8 或更高版本
• uv 包管理器
• 一个具有 API 访问权限的 Plex 媒体服务器

安装

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 Plex 媒体服务器集成：

npx -y @smithery/cli install @djbriane/plex-mcp --client claude

手动安装

1. 克隆此仓库：

   git clone <repository-url>
   cd plex-mcp
   

2. 使用 uv 安装依赖项：

   uv venv
   source .venv/bin/activate
   uv sync
   

3. 为您自己的 Plex 服务器配置环境变量：

   • PLEX_TOKEN: 您的 Plex 认证令牌
   • PLEX_SERVER_URL: 您的 Plex 服务器 URL（例如：http://192.168.1.100:32400）

查找您的 Plex 令牌

您可以通过以下方式找到您的 Plex 令牌：

• 登录到 Plex Web 应用程序
• 打开开发者工具
• 在控制台标签页中粘贴并运行：

  window.localStorage.getItem('myPlexAccessToken')
  

与 Claude 一起使用

向您的 Claude 应用添加以下配置：

{
    "mcpServers": {
        "plex": {
            "command": "uv",
            "args": [
                "--directory",
                "FULL_PATH_TO_PROJECT",
                "run",
                "src/plex_mcp/plex_mcp.py"
            ],
            "env": {
                "PLEX_TOKEN": "YOUR_PLEX_TOKEN",
                "PLEX_SERVER_URL": "YOUR_PLEX_SERVER_URL"
            }
        }
    }
}

可用命令

Plex MCP 服务器提供了这些命令：

运行测试

此项目包括单元测试和集成测试。请按照以下说明运行每种类型的测试：

单元测试

单元测试使用虚拟数据来验证每个模块的功能，而无需连接到实际的 Plex 服务器。

要运行所有单元测试：

uv run pytest

集成测试

集成测试针对一个实际的 Plex 服务器运行，使用 .env 文件中定义的环境变量。首先，在项目根目录下创建一个 .env 文件，并填写您的 Plex 配置：

PLEX_SERVER_URL=https://your-plex-server-url:32400
PLEX_TOKEN=yourPlexTokenHere

集成测试带有 integration 标记。仅运行集成测试：

uv run pytest -m integration

如果您遇到与 Plex 服务器连接的问题，请尝试运行集成测试以帮助排查问题。

代码风格和约定

• 模块结构：
  使用清晰的节标题来组织导入、日志设置、实用函数、类定义、全局辅助函数、工具方法以及主执行（通过 if __name__ == "__main__": 保护）。

• 命名：
  类使用驼峰命名法（CamelCase），函数、变量和固定装置使用小写下划线命名法（lower_snake_case）。在测试中，先列出内置的固定装置（例如 monkeypatch），然后再列出自定义的固定装置。

• 文档与注释：
  每个模块、类和函数都应包含简洁的文档字符串，并且对于复杂的逻辑添加内联注释。

• 错误处理与日志记录：
  使用 Python 的 logging 模块，并保持错误消息的一致性（以“ERROR:”为前缀），同时明确地处理异常。

• 异步模式：
  将 I/O 密集型函数定义为异步函数，并使用 asyncio.to_thread() 来处理阻塞操作。