Plex MCP Server

Plex MCP サーバー

これは、Plex Media Server API と連携して映画を検索し、プレイリストを管理する Python ベースの MCP サーバーです。PlexAPI ライブラリを使用して、お使いの Plex サーバーとスムーズに連携します。

スクリーンショット

Plex MCP サーバーの動作例をいくつか紹介します。

1. Plex ライブラリから監督名で映画を検索する

監督名を指定して、Plex ライブラリ内の映画を検索します。たとえば、「Alfred Hitchcock」を検索すると、ライブラリにある彼の映画の一覧が表示されます。

---

2. 監督の映画のうちライブラリにないものを探す

特定の監督の映画のうち、Plex ライブラリにないものを特定します。コレクションの不足を見つけるのに役立ちます。

---

3. Plex ライブラリにプレイリストを作成する

検索で見つかった映画を使って、Plex ライブラリに新しいプレイリストを作成します。これにより、ライブラリを効率的に整理できます。

セットアップ

前提条件

• Python 3.8 以降
• uv パッケージマネージャー
• API アクセスが可能な Plex Media Server

インストール

Smithery 経由でインストールする

Smithery 経由で Plex Media Server Integration for Claude Desktop を自動的にインストールするには、次の手順に従います。

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 にサインインします
• 開発者ツールを開きます
• コンソールタブで、次のコードを貼り付けて実行します。

  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）をカスタムフィクスチャより先に記述します。

• ドキュメントとコメント：
  すべてのモジュール、クラス、関数に簡潔な docstring を記述し、複雑なロジックにはインラインコメントを付けます。

• エラー処理とロギング：
  Python の logging モジュールを使用し、「ERROR:」を先頭に付けた一貫性のあるエラーメッセージと、明示的な例外処理を用います。

• 非同期処理のパターン：
  I/O バウンドな関数は async として定義し、ブロッキング処理には asyncio.to_thread() を使用します。