Plex MCP 服务器

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

截图

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

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

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

2. 查找导演遗漏的电影

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

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

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

设置

先决条件

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

安装

通过 Smithery 安装

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

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

手动安装

克隆此存储库：
git clone <repository-url> cd plex-mcp
使用uv安装依赖项：
uv venv source .venv/bin/activate uv sync
为您的 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 服务器公开以下命令：

命令	描述	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

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

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

Plex MCP Server

Integrations