Plex MCP 服务器

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

截图

以下是 Plex MCP 服务器工作原理的一些示例：

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

通过指定导演姓名，即可在您的 Plex 影库中搜索电影。例如，搜索“阿尔弗雷德·希区柯克”即可返回您影库中该导演的电影列表。

2. 查找导演遗漏的电影

识别 Plex 库中缺少的某位特定导演的电影。这有助于您发现收藏中的不足之处。

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

使用搜索到的电影在 Plex 库中创建新的播放列表。这样您就可以高效地整理您的库。

Related MCP server: moviefinder-mcp

设置

先决条件

• Python 3.8 或更高版本

• uv包管理器

• 具有 API 访问权限的 Plex 媒体服务器

安装

通过 Smithery 安装

要通过Smithery自动为 Claude Desktop 安装 Plex Media Server Integration：

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 网页应用

• 打开开发者工具

• 在控制台选项卡中，粘贴并运行：

  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

集成测试

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

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

集成测试带有集成标记。要仅运行集成测试，请执行以下操作：

uv run pytest -m integration

如果您遇到 Plex 服务器的连接问题，请尝试运行集成测试来帮助解决问题。

代码风格和约定

• 模块结构：
  使用清晰的节标题进行导入、日志设置、实用程序功能、类定义、全局帮助程序、工具方法和主要执行（由if __name__ == "__main__":保护）。

• 命名：
  类使用驼峰式命名 (CamelCase)，函数、变量和 Fixture 使用小写蛇形命名 (lower_snake_case)。在测试中，将内置 Fixture（例如monkeypatch ）列在自定义 Fixture 之前。

• 文档和评论：
  为每个模块、类和函数包含简洁的文档字符串，并为复杂的逻辑提供内联注释。

• 错误处理和日志记录：
  使用 Python 的logging模块，其中包含一致的错误消息（前缀“ERROR：”）和明确的异常处理。

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