Plex MCP Server

Plex MCP 服务

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

截图

以下是 Plex MCP 服务的部分使用示例：

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

指定导演姓名，即可搜索 Plex 媒体库中的电影。例如，搜索“Alfred Hitchcock”会返回媒体库中他的电影列表。

---

2. 查找导演的缺失电影

查找 Plex 媒体库中缺少的某位导演的电影，帮助您发现收藏中的遗漏。

---

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

使用搜索结果中的电影，在 Plex 媒体库中创建新的播放列表，以便高效整理媒体库。

设置

前置要求

• Python 3.8 或更高版本
• uv 包管理器
• 可通过 API 访问的 Plex Media Server

安装

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 Plex Media Server 集成：

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 App
• 打开开发者工具
• 在 Console 标签页中粘贴并运行：

  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 服务提供以下命令：

命令	说明	OpenAPI 参考
search_movies	使用各种筛选条件（例如标题、导演、类型）搜索媒体库中的电影，并支持使用 limit 参数控制结果数量。	/library/sections/{sectionKey}/search
get_movie_details	获取特定电影的详细信息。	/library/metadata/{ratingKey}
get_movie_genres	获取特定电影的类型。	/library/sections/{sectionKey}/genre
list_playlists	列出 Plex 服务上的所有播放列表。	/playlists
get_playlist_items	获取特定播放列表中的项目。	/playlists/{playlistID}/items
create_playlist	使用指定的电影创建新播放列表。	/playlists
delete_playlist	从 Plex 服务中删除播放列表。	/playlists/{playlistID}
add_to_playlist	将电影添加到现有播放列表。	/playlists/{playlistID}/items
recent_movies	获取媒体库中最近添加的电影。	/library/recentlyAdded

运行测试

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

单元测试

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

运行所有单元测试：

uv run pytest

集成测试

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

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() 处理阻塞操作。