Plex MCP Server

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

屏幕截图

这里有一些示例展示了Plex MCP服务器的工作方式：

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

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

---

2. 查找特定导演缺少的电影

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

---

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

使用搜索找到的电影在您的Plex库中创建新的播放列表。这允许您高效地组织您的库。

安装

预备条件

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

安装

通过Smithery安装

要通过Smithery自动安装Plex媒体服务器集成到Claude桌面：

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",
                "项目完整路径",
                "run",
                "src/plex_mcp/plex_mcp.py"
            ],
            "env": {
                "PLEX_TOKEN": "您的Plex令牌",
                "PLEX_SERVER_URL": "您的Plex服务器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

集成测试

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

PLEX_SERVER_URL=https://您的Plex服务器URL:32400
PLEX_TOKEN=您的Plex令牌

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

uv run pytest -m integration

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

代码风格和约定

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

• 命名： 类使用CamelCase，函数、变量和固定装置使用lower_snake_case。在测试中，列出内置固定装置（如monkeypatch）之前自定义的固定装置。

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

• 错误处理与日志记录： 使用Python的logging模块，具有统一的错误消息（前缀“ERROR:”）和显式的异常处理。

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