Plex MCP

🚀 Plex MCP 服務器

這是一個基於 Python 的 MCP 服務器，它與 Plex 媒體服務器 API 集成，可用於搜索電影和管理播放列表。該服務器藉助 PlexAPI 庫，實現了與 Plex 服務器的無縫交互。

🚀 快速開始

Plex MCP 服務器能讓你輕鬆與 Plex 媒體服務器交互，實現電影搜索和播放列表管理等功能。以下是使用前的安裝和配置步驟。

✨ 主要特性

• 按導演查找電影：可通過指定導演姓名在 PLEX 庫中搜索電影。
• 查找缺失電影：能識別特定導演作品中不在 PLEX 庫中的電影。
• 創建播放列表：可使用搜索到的電影在 PLEX 庫中創建新播放列表。

📦 安裝指南

先決條件

• Python 3.8 或更高版本
• uv 包管理器
• 帶有 API 訪問權限的 Plex 媒體服務器

安裝方法

使用 Smithery 自動安裝

要通過 Smithery 自動為 Claude 桌面安裝 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 install

3. 運行服務器：

uv run python src/main.py

📚 詳細文檔

配置

環境變量

創建一個 .env 文件，並添加以下內容：

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

使用方法

運行服務器後，您可以通過 API 或 Web 界面與 Plex 交互。

命令列表

以下是 Plex MCP 服務器支持的主要命令：

整合測試

端到端測試

在項目根目錄下運行以下命令執行端到端測試：

uv run pytest tests/

集成測試

要運行集成測試，請先創建一個包含 Plex 配置的 .env 文件，然後運行：

uv run pytest -m integration

代碼風格和約定

• 模塊結構：使用清晰的部分標題來區分導入、日誌設置、實用函數、類定義、全局輔助工具和主執行部分（由 if __name__ == "__main__": 保護）。
• 命名約定：使用 CamelCase 定義類，使用 lower_snake_case 定義函數、變量和 fixtures。在測試中，將內置 fixture（如 monkeypatch）列在自定義 fixture 之前。
• 文檔與註釋：每個模塊、類和函數都包含簡潔的 docstring，併為複雜邏輯添加內聯註釋。
• 錯誤處理與日誌記錄：使用 Python 的 logging 模塊，使用一致的錯誤消息（以 “ERROR:” 為前綴）和顯式的異常處理。
• 異步模式：將 I/O 綁定函數定義為異步，並在處理阻塞操作時使用 asyncio.to_thread()。

🔍 截圖

1. 按導演查找 PLEX 庫中的電影

通過指定導演姓名在您的 PLEX 庫中搜索電影。例如，搜索 "Alfred Hitchcock" 將返回他在您庫中的電影列表。

2. 查找某個導演的缺失電影

識別特定導演作品中不在您 PLEX 庫中的電影。這有助於發現您收藏中的空白。

3. 在您的 PLEX 庫中創建播放列表

使用搜索到的電影在您的 PLEX 庫中創建新播放列表。這樣可以方便地組織您的庫。