Plex Director

plex-director-mcp

Plex Director は、Plex と Servarr のメディア環境向けのセルフホスト可能なアシスタントです。Plex、Radarr、Sonarr、Prowlarr、SABnzbd、qBittorrent、Tautulli、TMDb（必要に応じて、SSH 経由で Linux ホストにも）接続し、次の 2 つの方法で利用できます。

• Claude Desktop 用の MCP サーバー — 所有しているコンテンツの検索、映画が見つからない理由の調査、映画の追加、インデクサーやダウンロードキューの確認、バッチジョブの実行を Claude に依頼できます。
• ウェブダッシュボード — チャットボックス（「Harrison Ford の映画で 4K のものはどれですか？」）、サーバーのステータス、ホストの使用状況、ダウンロードキュー、インデクサーの状態、バックグラウンドジョブを備えたブラウザー UI です。

連携するアプリの近くにある LAN 上で実行する、家庭向けの環境を想定して構築されています。

警告

Plex Director は、接続するすべてのサービスの API キーを保持し、それらを読み取るだけでなく変更もできます。Radarr への映画の追加やダウンロード検索の開始、qBittorrent からの停止したトレントの削除、バッチアップグレードジョブの実行、Servarr のバックアップの起動が可能です。映画の追加は選択してから確定する手順を経て、バッチジョブは実行前に計画されますが、停止したトレントの削除とバックアップの開始は要求と同時に行われ、チャットと Claude Desktop はあなたのキーを使って操作します。WEB_PASSWORD を設定し、ダッシュボードをパブリックインターネットに公開しないでください。また、セキュリティ要件を確認してください。

ドキュメント

• クイックスタート、インストール、アップグレードとバックアップ、リリースの検証。
• ユーザーガイド：ダッシュボードの各ページ、Query チャット、MCP ツールについて説明します。ドキュメントの索引にすべての項目が掲載されています。
• アーキテクチャ：コンポーネント、その利用者、質問が各コンポーネントをどのように流れるかについて説明します。
• セキュリティ要件：Plex Director が保護する対象と保護しない対象、およびその根拠となる保証ケースについて説明します。
• ロードマップ：プロジェクトの今後の方向性と、対応しないことについて説明します。
• アクセシビリティ：現在のダッシュボードの対応状況と、既知の課題について説明します。
• 外部インターフェース（ダッシュボードの HTTP API は docs/api/openapi.json に記載されています）、依存関係と脆弱性管理。
• サポート：修正が提供されるバージョンとその期間について説明します。変更履歴。
• コントリビューション、行動規範、ガバナンス、脆弱性の報告。

目次

• ドキュメント
• できること
• クイックスタート
• Docker
  • サポート対象のアーキテクチャ
  • イメージタグ
  • アプリケーションのセットアップ
  • 使い方 — Docker Compose · Docker CLI · Docker 経由の Claude Desktop
  • パラメーター
  • 環境変数のリファレンス
  • 読み取り専用および非 root での実行
  • 更新
  • ローカルでのビルド
• Docker を使わずに実行する（Claude Desktop）
• ウェブダッシュボード
• MCP ツール
• セキュリティ
• 開発
• CI/CD
• ライセンス

できること

• 所有しているものを探す。 Plex ライブラリ内の映画やテレビ番組を、ジャンル、俳優、タイトル、年、ライブラリで検索できます（たとえば 4K ライブラリだけなど）。すべてのライブラリを一度に検索できます。HD と 4K の両方にあるタイトルは、両方のライブラリを表示した1件の結果になります。番組にはシーズン数とエピソード数、視聴済みの割合も表示されます。Sports のようなライブラリは、名前を指定しない限り検索対象から除外できます。
• 全エピソードそろっていますか？ 番組について尋ねると、Sonarr のエピソード一覧から、放送済みエピソードのうちダウンロード済みの数と、欠けているエピソードを正確に確認できます。また、エピソードが欠けている番組を、ほぼそろっている番組も含めて順位付きで尋ねることもできます。未放送のエピソードとスペシャルは、欠けているものとして数えません。欠けているエピソードについては、Sonarr の履歴とダウンロードキューをもとに、その理由も確認できます。
• 何が放送され、次回はいつですか？ 今後数日間に放送されるエピソードを、初回放送や最終回の印を付けて確認できます。また、特定の番組の次回放送日や、まだ日程が発表されていないことを尋ねることもできます。
• 次に何を観るべきですか？ 次に観るものとして、視聴中の各番組の次のエピソードと、最後まで観ていない映画を尋ねることができます。各映画をどこまで観たかも表示されます。
• 何を観て、何を長らく観ていないのでしょうか？ 未視聴の番組、視聴を始めたものの最後まで観ていない番組、何年も観ていない映画、または新しく追加された作品を、単独でもジャンルやライブラリなどの条件と組み合わせても尋ねることができます。Plex 上では視聴済みでも日付が記録されていないタイトルは、推測せずに別枠で集計します。
• 所有済みと未所有を比較する。 俳優の TMDb フィルモグラフィー（映画とテレビ番組）を調べ、該当するタイトルのうち Plex にあるものとないものを確認できます。映画または番組に絞ったり、年の範囲や「in 4K」で絞り込んだりすることもできます。トークショーへの出演や「Self」としての出演は除外され、同じ作品で俳優が複数の役を演じていてもタイトルは1回だけ表示されます。
• 映画の問題を調べて追加する。 Radarr のメタデータ、履歴、ダウンロードキューをたどって映画が見つからない理由を確認できます。または TMDb を検索して、一覧から選んだ映画をダウンロード検索とともに Radarr に追加できます。
• ダウンロードとインデクサーを確認する。 SABnzbd と qBittorrent のキューを確認し、停止したトレントを整理して、Prowlarr のすべてのインデクサーの状態を確認できます（バックオフ中のものも含みます）。
• バッチジョブを安全に実行する。 映画アップグレードのバッチを計画し、レート制限付きの実行機能で1分に1本ずつ検索できます。一時停止、再開、キャンセルができ、Radarr が応答しなくなった場合は自動で一時停止します。
• ホストを監視する。 SSH 経由で Linux ホストの CPU、メモリ、ディスク、稼働時間、Docker コンテナーの状態を確認できます。また、必要に応じて Radarr、Sonarr、Prowlarr の組み込みバックアップも実行できます。各ホストの SSH キーは初回接続時に記憶され、キーが変更されると、承認するまで接続を拒否します。
• 利用状況を把握する。 Tautulli を通じて、Plex のライブストリームと視聴統計を確認できます。
• 最新情報を受け取る。 バッチジョブの完了時や一時停止時に、任意で Discord 通知を受け取れます。

クイックスタート

v1.2.0 以降、Plex Director は io.github.HoneyBearTech/plex-director-mcp として公式 MCP レジストリに登録されているため、レジストリを参照できる MCP クライアントから直接インストールできます（設定は server.json に記載されています）。それ以外の場合、最も手軽に試す方法は Docker Compose です。

---
services:
  plex-director:
    image: honeybeartech/plex-director-mcp:latest
    container_name: plex-director
    environment:
      - WEB_PASSWORD=choose-a-password
    volumes:
      - ./data:/app/data
    ports:
      - 3000:3000
    restart: unless-stopped

docker compose up -d

次に http://localhost:3000 を開いてサインインし、Settings ページでサービス（Radarr、Sonarr、Prowlarr、SABnzbd、qBittorrent、Tautulli、Plex、TMDb）を設定してください。各オプションを網羅した完全なガイドは、以下の Docker にあります。代わりに Claude Desktop から利用するには、Claude Desktop via Docker を参照してください。

Docker

イメージは両方のレジストリに公開されており、どちらも署名されています（CI/CD を参照）。

レジストリ	イメージ
Docker Hub	honeybeartech/plex-director-mcp
GitHub Container Registry	ghcr.io/honeybeartech/plex-director-mcp

以下の内容はどちらでも利用できます。例では Docker Hub を使用しています。

対応アーキテクチャ

マルチアーキテクチャマニフェストが公開されているため、イメージをプルすると、お使いのマシンに適したものが自動的に取得されます。

アーキテクチャ	利用可能
x86-64 (linux/amd64)	✅
arm64 (linux/arm64)	✅

イメージタグ

タグ	説明
latest	main ブランチの最新ビルドです。まだバージョン番号が付けられていない変更も含まれます。
1.4.0	特定のリリースです。アップグレードするタイミングを選びたい場合は、いずれかのタグを固定してください。
1.1	マイナーバージョンの最新パッチリリースです。
sha-<commit>	固定や二分探索に使える、特定のコミットのビルドです。

番号付きバージョンのリリースノートは、Releases ページにあります。

アプリケーションのセットアップ

1. 使用方法の例のいずれかを使ってコンテナを起動し、http://<host>:3000 で Web UI を開きます。
2. パスワードを設定します。 コンテナの環境変数に WEB_PASSWORD を追加してください。設定しない場合、ポートにアクセスできる人なら誰でも設定ページを含むダッシュボードを利用でき、警告バナーも表示されます。セキュリティを参照してください。
3. サービスを追加します。 Settings を開き、各タブに入力します。すべての項目は環境変数でも指定できます（リファレンスを参照）。自動セットアップに便利です。実際に使用するサービスだけを設定すれば十分です。
4. チャットボックスに頭脳を与えます。 Query ページでは Claude を使って質問に回答するため、コンテナの環境変数に ANTHROPIC_API_KEY が必要です。これは従量課金制の Anthropic API キーで、Claude のサブスクリプションとは別のものです。これがなくても、ダッシュボードのその他の機能は動作します。
5. データボリュームを保持します。 設定、ジョブ履歴、サインイン状態を維持するためのシークレットは、/app/data にある SQLite データベースに保存されます。ここにボリュームをマウントしてください。マウントしない場合、コンテナを再作成するたびにデータが失われます。

各認証情報の確認場所：

サービス	入力する内容
Radarr、Sonarr、Prowlarr	URL と、Settings → General にある API キー。
SABnzbd	URL と、Config → General にある API キー。
qBittorrent	Web UI の URL、ユーザー名、パスワード。
Tautulli	URL（/api/v2 を除く）と、Settings → Web Interface にある API キー。
Plex	サーバー URL（例：http://192.168.1.10:32400）と X-Plex-Token：Plex Web で任意の映画を開き、⋯ → Get Info → View XML を選択して、アドレスバーから X-Plex-Token= の値をコピーします。パスワードと同じように扱ってください。
TMDb	TMDb アカウントの API 設定にあるAPI Read Access Token（長いほう）で、短い v3 API キーではありません。

ネットワーク： コンテナ内の localhost はサーバーではなく、コンテナ自体を指します。各サービスの LAN アドレス（例：http://192.168.1.10:7878）を使うか、ほかのアプリが同じ Compose プロジェクトまたは Docker ネットワークにある場合は、サービス名（http://radarr:7878）を使ってください。

使用方法

コンテナの作成を始める際に役立つ例をいくつか紹介します。Docker Compose の使用をおすすめします。

Docker Compose（推奨）

---
services:
  plex-director:
    image: honeybeartech/plex-director-mcp:latest
    container_name: plex-director
    environment:
      - WEB_PASSWORD=choose-a-password
      - ANTHROPIC_API_KEY=sk-ant-your-key #optional, needed for the Query chat
      - RADARR_URL=http://192.168.1.10:7878 #optional, or set on the Settings page
      - RADARR_API_KEY=your_radarr_api_key #optional
      - PLEX_URL=http://192.168.1.10:32400 #optional
      - PLEX_TOKEN=your_plex_token #optional
      - TMDB_API_KEY=your_tmdb_read_access_token #optional
      - DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/... #optional
    volumes:
      - /path/to/plex-director/data:/app/data
      - /path/to/ssh/id_ed25519:/ssh/id_ed25519:ro #optional, for host monitoring over SSH
    ports:
      - 3000:3000
    restart: unless-stopped

イメージにはヘルスチェックが組み込まれているため、起動すると docker ps に healthy と表示されます。ヘルスチェックを追加する必要はありません。

認証情報を compose ファイルに記載しないようにするには、隣に .env 形式のファイルを置き、認証情報を直接記述する代わりにそのファイルを参照します。

    env_file:
      - plex-director.env

次に、起動します。

docker compose up -d

Docker CLI

docker run -d \
  --name=plex-director \
  -e WEB_PASSWORD=choose-a-password \
  -e ANTHROPIC_API_KEY=sk-ant-your-key \
  -p 3000:3000 \
  -v /path/to/plex-director/data:/app/data \
  --restart unless-stopped \
  honeybeartech/plex-director-mcp:latest

リファレンスにあるほかの変数を -e フラグで追加するか、ファイルに記述して --env-file plex-director.env を渡してください。SSH ホストの監視には、-v /path/to/ssh/id_ed25519:/ssh/id_ed25519:ro も追加してください。

--env-file は Node 用の .env ファイルとは異なります。 Docker は値をそのまま読み取ります。値を引用符で囲まず、同じ行で値の後ろにコメントを記述しないでください（KEY=abc # my key は値 abc # my key になります）。コメントは独立した行に記述してください。

Docker 経由での Claude Desktop

同じイメージが MCP サーバーでもあり、stdio 経由で通信します。Claude Desktop の設定（設定 → 開発者 → 設定を編集、claude_desktop_config.json）で、docker run -i を使って実行するよう指定してください。

{
  "mcpServers": {
    "plex-director": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/absolute/path/to/plex-director.env",
        "-v", "plex-director-data:/app/data",
        "honeybeartech/plex-director-mcp:latest"
      ]
    }
  }
}

Claude Desktop を再起動すると、plex-director サーバーがツールプロバイダーとして表示されます（26 個のツール。以下の一覧を参照）。注意事項：

• MCP は stdin/stdout 経由で通信するため、-i が必要です。-t は追加しないでください。
• -p は不要です。Web ダッシュボードもこのコンテナ内で起動しますが、Compose のコンテナではなく、このコンテナからアクセスしたい場合に限り、そのポートを公開してください。
• 上記の長時間稼働するコンテナも実行する場合は、両方に同じデータボリューム（またはバインドマウント）を指定し、設定とジョブ履歴を共有してください。
• Claude が stdin を閉じてもコンテナは実行を続けます。Claude Desktop を終了すると停止します。または、docker stop を使用してください。

パラメーター

コンテナイメージは、実行時に渡すパラメーターで設定します。これらのパラメーターはコロンで区切られ、それぞれ <外部>:<内部> を示します。たとえば、-p 8080:3000 を指定すると、コンテナ内部のポート 3000 を公開し、コンテナ外部のポート 8080 でホストの IP からアクセスできるようになります。

パラメーター	機能
-p 3000:3000	Web ダッシュボードです。ホスト側で別のポートを使うには、左側の数字を変更してください。
-e WEB_PASSWORD=	Web ダッシュボードのパスワードです。強く推奨します。
-e ANTHROPIC_API_KEY=	Query チャットを有効にします。
-e RADARR_URL= など	サービスへの接続情報です。リファレンスを参照してください。設定ページで入力できるため、省略可能です。
-v /app/data	SQLite データベースです。保存した設定、ジョブ履歴、ログインセッション用のシークレットが含まれます。ここにボリュームをマウントしてください。
-v /ssh/id_ed25519:ro	省略可能です。 ホストの監視に使う SSH 秘密鍵です（-e SSH_KEY_PATH=/ssh/id_ed25519 を指定）。

環境変数のリファレンス

コンテナの起動に必要な設定はありません。設定なしで起動し、設定ページで情報を入力できます。

サービス接続。 初回起動時にこれらの値はデータベースにコピーされ、その後はデータベースに保存された値が優先されます（設定ページで編集する値です）。後からこれらの変数を変更しても何も起きない場合は、それが理由です。設定ページで変更するか、データベースを削除してください。

変数	説明
RADARR_URL、RADARR_API_KEY	Radarr。映画のステータス確認、診断、映画の追加、一括ジョブに使用します。
RADARR_DEFAULT_QUALITY_PROFILE	省略可能です。 映画の追加時に新しい映画へ適用する画質プロファイルの名前です。空欄にすると、Radarr の最初のプロファイルが使用されます。設定ページの Radarr タブでも設定できます。
SONARR_URL、SONARR_API_KEY	Sonarr。省略可能です。テレビ番組のエピソードの揃い具合の確認とバックアップに使用します。
PROWLARR_URL、PROWLARR_API_KEY	Prowlarr。インデクサーの状態確認とバックアップに使用します。
SABNZBD_URL、SABNZBD_API_KEY	SABnzbd。キューの確認と、メディアが見つからない場合の診断に使用します。
QBITTORRENT_URL、QBITTORRENT_USER、QBITTORRENT_PASS	qBittorrent Web UI。
TAUTULLI_URL、TAUTULLI_API_KEY	Tautulli。ストリームと視聴統計に使用します。
PLEX_URL、PLEX_TOKEN	Plex。所有しているコンテンツの検索に使用します。
PLEX_SKIP_LIBRARIES	省略可能です。 検索対象から除外する Plex ライブラリ名をカンマ区切りで指定します（名前全体。大文字と小文字は区別しません）。例：Sports。質問で指定したライブラリ名（「Sports の中」など）は、引き続き検索されます。空欄にすると、すべてのライブラリを検索します。設定ページの Plex タブでも設定できます。
TMDB_API_KEY	TMDb の API Read Access Token。俳優の出演作品一覧と映画選択グリッドに使用します。
UBUNTU_HOSTS	SSH 経由で監視するホストをカンマ区切りで指定します。例：192.168.1.10,192.168.1.11。標準以外の SSH ポートを使う場合は、:ポート番号 を追加します（192.168.1.10:2222）。
SSH_USER	これらのホストに接続する SSH ユーザーです。

コンテナ設定。 これらは毎回環境変数から読み込まれ、データベースには保存されず、設定ページにも表示されません。

変数	デフォルト	説明
WEB_PASSWORD	(なし)	ダッシュボードへのログインを必須にします。変更すると、全員がサインアウトします。
WEB_ALLOWED_HOSTS	(なし)	WEB_PASSWORD を設定していない場合にのみ有効です。ダッシュボードが応答する追加のホスト名を、カンマ区切りで指定します（例：リバースプロキシの背後にある plex.example.com）。IP アドレス、localhost、1 語の名前、.local／.lan／.home.arpa／.internal の名前は常に使用できます。それ以外の名前は 403 になり、DNS リバインディング攻撃を防ぎます。* を指定するとチェックを無効にします。
WEB_TRUST_PROXY	(なし)	ダッシュボードの前段にあるリバースプロキシを、アドレスまたはサブネットでカンマ区切りにして指定します（例：192.168.40.10 または 192.168.40.0/24）。または loopback を指定します。ここからのリクエストのみが X-Forwarded-For と X-Forwarded-Proto を設定できるため、ログイン制限は実際のクライアントごとに適用され、HTTPS ではセッション Cookie が Secure になります。未設定の場合、両方のヘッダーは無視されます。true とホップ数は指定できません。
SETTINGS_ENCRYPTION_KEY	(なし)	データベースに保存されるサービスの認証情報を暗号化します（AES-256-GCM）。ランダムな 32 バイトを base64 または hex 形式で指定します。openssl rand -base64 32 で生成できます。保存済みの認証情報は次回起動時に暗号化されます。データベースを共有するすべてのコンテナで同じキーが必要です。また、キーがなければデータベースを利用できないため、バックアップとは別の場所にもコピーを保管してください。推奨です。
WEB_PORT	3000	コンテナ内でダッシュボードがリッスンするポートです。
ANTHROPIC_API_KEY	(なし)	Query チャット用の Anthropic API キーです。
SSH_KEY_PATH	(なし)	ホスト監視用の秘密鍵へのコンテナ内のパスです。コンテナのユーザーが読み取れる必要があります。
SSH_KEY_PASSPHRASE	(なし)	秘密鍵がパスフレーズで保護されている場合のパスフレーズです。
DISCORD_WEBHOOK_URL	(なし)	ジョブの完了時と一時停止時の通知に使う Discord Webhook です。
JOB_RUNNER_INTERVAL_SECONDS	60	ジョブランナーが開始済みのジョブを 1 本の映画分進める間隔です（最小値は 10、0 でランナーを無効にします）。

読み取り専用および非 root での実行

コンテナは 1.3.0 以降、非 root ユーザーの UID と GID 65532（distroless の nonroot）で実行されます。それ以前のバージョンは root で実行されていました。イメージにはシェルもパッケージマネージャーもなく、書き込み先はデータディレクトリのみです。そのため、読み取り専用ファイルシステムとケーパビリティなしでも実行できます。

services:
  plex-director:
    image: honeybeartech/plex-director-mcp:latest
    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    volumes:
      - /path/to/plex-director/data:/app/data
    ports:
      - 3000:3000

CLI を使う場合：--read-only --cap-drop ALL --security-opt no-new-privileges:true。

名前付きボリュームはそのまま使えます。Docker が新しいボリュームに /app/data のイメージ所有者を設定します。ホストフォルダーを使う場合は、まず UID 65532 の所有にする必要があります：sudo chown -R 65532:65532 /path/to/plex-director/data。代わりに別のユーザー（たとえば、すでにフォルダーを所有しているユーザー）で実行するには、user: "1000:1000"（または --user 1000:1000）を追加します。データディレクトリに書き込めない場合、コンテナは起動時に停止し、実行すべき chown コマンドを表示します。データが root の所有になっている 1.2.x 以前からアップグレードする場合は、アップグレードを参照してください。SSH ホスト監視を使用する場合は、マウントした鍵もコンテナのユーザーが読み取れる必要があります。

更新

設定とジョブ履歴はデータボリュームに保存されるため、更新時はコンテナを置き換えるだけです。

Docker Compose

docker compose pull plex-director
docker compose up -d
docker image prune

Docker CLI

docker pull honeybeartech/plex-director-mcp:latest
docker stop plex-director
docker rm plex-director
# ...then run the same `docker run` command as before
docker image prune

ダウンロードを検証する。 公開されているすべてのイメージは、管理するキーを必要としない GitHub の OIDC ID を使って、cosign で署名されています。

cosign verify \
  --certificate-identity-regexp "https://github.com/HoneyBearTech/plex-director-mcp/.*" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  honeybeartech/plex-director-mcp:latest

ローカルでのビルド

git clone https://github.com/HoneyBearTech/plex-director-mcp.git
cd plex-director-mcp
docker build -t plex-director-mcp .

.dockerignore により、.env、ローカルデータベース、その他のシークレットがビルドコンテキストに含まれないようになっています。シークレットをイメージに含めないでください。実行時に渡してください。

Docker を使わずに実行する（Claude Desktop）

Node.js 24 が必要です。

git clone https://github.com/HoneyBearTech/plex-director-mcp.git
cd plex-director-mcp
npm install
# Build the dashboard; without this the web UI has nothing to serve.
cd web && npm install && npm run build && cd ..

リポジトリのルートに .env ファイルを作成し、使用するサービスを設定します（すべて任意です。サービスの詳細は後から Settings ページで入力することもできます）。

RADARR_URL=http://radarr:7878
RADARR_API_KEY=your_radarr_api_key
RADARR_DEFAULT_QUALITY_PROFILE=Your Profile Name
SONARR_URL=http://sonarr:8989
SONARR_API_KEY=your_sonarr_api_key
PROWLARR_URL=http://prowlarr:9696
PROWLARR_API_KEY=your_prowlarr_api_key
SABNZBD_URL=http://sabnzbd:8080
SABNZBD_API_KEY=your_sabnzbd_api_key
QBITTORRENT_URL=http://qbittorrent:8080
QBITTORRENT_USER=your_qbittorrent_user
QBITTORRENT_PASS=your_qbittorrent_password
TAUTULLI_URL=http://tautulli:8181
TAUTULLI_API_KEY=your_tautulli_api_key
PLEX_URL=http://plex:32400
PLEX_TOKEN=your_plex_token
TMDB_API_KEY=your_tmdb_read_access_token
ANTHROPIC_API_KEY=your_anthropic_api_key
UBUNTU_HOSTS=192.168.1.10,192.168.1.11
SSH_USER=your_ssh_username
SSH_KEY_PATH=/path/to/id_ed25519
SSH_KEY_PASSPHRASE=only_if_the_key_has_one
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
WEB_PORT=3000
WEB_PASSWORD=choose-a-password

各項目の役割については、リファレンスをご覧ください。よくある問題が 2 つあります。

• コメントは値の後ではなく、独立した行に記述してください（KEY=abc # note とすると、一部のツールではコメントが値の一部になります）。
• スペースを含むパスは、値全体を引用符で囲む必要があります： /Users/me/.ssh/'my key' ではなく、SSH_KEY_PATH="/Users/me/.ssh/my key" とします。

Claude Desktop にサーバーを追加します（Settings → Developer → Edit Config）。

{
  "mcpServers": {
    "plex-director": {
      "command": "npx",
      "args": ["-y", "tsx", "/absolute/path/to/plex-director-mcp/src/index.ts"],
      "env": { "NODE_ENV": "production" }
    }
  }
}

パスを実際のものに置き換えて、Claude Desktop を再起動してください。サーバーは同じプロセス内で WEB_PORT 上に Web ダッシュボードを起動します。

Web ダッシュボード

ダッシュボードは MCP サーバーと同じプロセス内で WEB_PORT（デフォルトは 3000）上に起動します。

ページ	表示内容
Query	Claude と各サービスを使ってライブラリに関する質問に回答するチャットボックスです。検索結果はポスター付きのテーブルで表示されます（番組ではシーズン、エピソード、視聴状況も表示されます）。最初の 50 件が表示され、ボタンで展開できます。追加の質問にもコンテキストが引き継がれ、New chat で会話をやり直せます。ANTHROPIC_API_KEY が必要です。
Server Status	Plex のライブストリームと視聴統計（Tautulli から取得）です。
Node Utilization	各 SSH ホストの CPU、メモリ、ディスク、稼働時間、コンテナの状態です。到達できないホストにはその理由が表示されます。SSH キーが変更されたホストには、Trust new key ボタン付きの警告が表示されます（Security を参照）。
Queues	SABnzbd と qBittorrent のダウンロードキューです。
Indexers	すべての Prowlarr インデクサーの状態（正常、直近の失敗、バックオフ中、無効）と、Prowlarr 自体のヘルス警告です。
Jobs	バッチジョブとその進捗状況です。読み取り専用です。ジョブの開始、一時停止、キャンセルは Claude から行ってください。
Settings	各サービスの接続情報です。シークレットがブラウザーに返されることはありません。設定済みかどうかだけが返されます。

WEB_PASSWORD を設定するとログインが必須になります。サインインページの後、署名付きの 7 日間有効なセッション Cookie が発行されます（HTTPS 経由で提供される場合は、自動的に Secure 属性が付きます）。ログイン失敗にはレート制限が適用されます。ログアウトで消去されるのはブラウザーに保存された情報だけです。すべてのセッションを無効にするには、パスワードを変更してください。

ヘルスチェックは GET /healthz で、{"ok":true} を返し、ログインは不要です。Docker イメージでは、curl が含まれていないため、Node 自体を使って 30 秒ごとにヘルスチェックを実行します。チェック対象のポートは、設定されている WEB_PORT です。

MCP ツール

Claude Desktop では 26 個のツールを利用できます。★印の付いた 12 個のツールは、ダッシュボードの Query チャットでも使用されます。

サーバーは MCP クライアントに短い使用ガイダンスも送信します。どの種類の質問にどのツールが適しているか、またサービスに変更を加える操作の前には確認するよう案内します。同じガイダンスは、スキルを読み込むエージェント（Claude Code など）向けの Agent Skill と、Query チャットのプロンプトにも記載されています。ガイダンスは src/guidance.ts に一度だけ記述されています。

ライブラリ

ツール	機能
★ search_plex_library	すべてのライブラリを対象に、ジャンル、出演者、タイトル、年、ライブラリ（例：4k）で Plex ライブラリ内の映画やテレビ番組を検索します。また、映画のみ、または番組のみを検索することもできます。番組の場合はシーズン、エピソード、視聴状況を表示します。視聴状態（未視聴、視聴中、視聴済み）や「過去 N 年間未視聴」（一度も視聴していないタイトルは、追加された時点から数えます）で絞り込み、最近追加された順または最後に視聴した順に並べ替えます。ネットワークまたはスタジオ、コンテンツレーティング（TV-MA、R…）、視聴者評価、公開年（10 年単位）、または「過去 N 日間に追加」でさらに絞り込めます。視聴状態は、アプリが接続している Plex アカウントのものです。大量の検索結果はページ分けされます。
★ search_episodes	個々のテレビエピソードを検索します。「Entourage のあのエピソードで…」のような検索、タイトルでのエピソード検索、指定した期間に放送されたエピソード、番組のシーズン初回または最終回を検索できます。番組名を指定すると、エピソードのタイトル とあらすじ を検索します。番組名を指定しない場合は、Plex ではライブラリ全体のあらすじを検索できないため、タイトルと放送日のみを検索します。シーズン番号、エピソード番号、放送日、視聴状態を表示します。
★ get_on_deck	Plex の「On Deck」（視聴を続ける）から「次に何を見ればいいですか？」に答えます。一部まで再生した映画と、フォローしている各番組の次に視聴するエピソード（または途中まで視聴したエピソード）を、最近視聴した順に、各作品の視聴進捗とともに表示します。HD と 4K の両方で保存されている映画は 1 件として表示されます。映画のみ、番組のみ、または kids のようなライブラリに限定できます。Plex が報告するアイテム数は最大 50 件です。視聴状態は、アプリが接続している Plex アカウントのものです。
★ resolve_actor_filmography	俳優の TMDb フィルモグラフィーを、映画とテレビ番組（またはいずれか一方）で表示します。各タイトルには Plex にあるかどうかが示され、年の範囲、所有済み／未所有、ライブラリで絞り込めます。番組は TMDb ID で Plex と照合するため、TMDb との照合結果がない Plex の番組は所有済みとして認識されません。
★ check_series_completeness	「この番組のエピソードはすべてそろっていますか？」Sonarr のエピソード一覧をもとに、放送済みエピソードのうちダウンロード済みの数、不足しているシーズンとエピソード、未放送のエピソード、Sonarr が番組を監視しているか（残りを取得するか）を確認します。一部のみダウンロードされた未監視の番組を完了扱いする Sonarr の統計ではなく、エピソード自体を数えます。Plex がスキャンした内容は確認しません。
★ find_series_gaps	放送済みエピソードが不足しているテレビ番組を、不足数の多い順に表示します。ダウンロード済みの数と、Sonarr が残りを検索しているかどうかも確認できます。監視中、未監視、または積極的に検索中で絞り込み、「ほぼ完了」した番組向けに不足数でも絞り込めます。また、ダウンロード済みのエピソードがない番組を非表示にできます。
★ find_series_by_quality	Sonarr がダウンロードした動画の画質でテレビ番組を検索します。「720p でしか持っていない番組は？」「1080p 以上の番組は？」「画質が混在している番組は？」（アップグレード候補）などを検索できます。最も低い最高画質の番組から順に、各解像度のファイル数とともに表示します。Sonarr がダウンロードしたもののみを対象とするため、別の Plex 4K ライブラリにある 4K コピーは数えられません（Plex 検索で 4k ライブラリを使用してください）。読み取り専用です。
★ check_series_status	ある番組について Sonarr が把握している情報を表示します。監視中かどうか、画質プロファイルと保存場所、次のエピソードの放送日時、最後にダウンロードされた日時、ダウンロードキューの内容、放送済みエピソードのうちダウンロード済みの数を確認できます。
★ diagnose_missing_episodes	Sonarr の履歴とダウンロードキューをもとに、番組の放送済みエピソードにファイルがない 理由 を調べます。一度も取得されていない、取得されたがインポートされていない、ダウンロードに失敗した（Sonarr による理由も表示）、ファイルが削除された、キュー内で停止している、または未監視のため Sonarr が検索していない、といった理由を確認できます。シーズンまたは特定のエピソードに限定できます。読み取り専用です。
★ get_upcoming_episodes	Sonarr のカレンダーをもとに、今後放送されるテレビ番組を表示します。タイトルを指定しない場合は、「今週は何が放送されますか？」に答えます。Sonarr が監視している番組のうち、数日後まで（デフォルトは 7 日、最大 60 日）の放送エピソードを日ごとに表示し、シーズン初回と最終回には印を付け、すでにダウンロード済みのエピソードも示します。タイトルを指定すると、「この番組はいつ再開しますか？」に答え、次のエピソード、まだ予定がないこと、または番組が終了したことを表示します。Sonarr が監視していない番組は、表示を指定されない限り除外され、その数が報告されます。
★ check_movie_status	映画が Radarr に登録されているかどうかと、監視状態をアートワークとともに確認します。
★ diagnose_missing_media	Radarr のメタデータ、履歴、ダウンロードキューをたどり、映画が見つからない理由を調べます。
search_and_select_movies	TMDb を検索し、一致する候補を番号付きの一覧で表示します。
confirm_selected_choices	一覧から選択した番号の映画を、監視対象として Radarr に追加し、ダウンロード検索を開始します。すでに登録されている映画は報告され、重複して追加されません。指定した画質プロファイルを使用します。指定がない場合は、Settings ページの Radarr タブに設定されたデフォルトのプロファイルを使用し、それもない場合は Radarr の最初のプロファイルを使用します。ルートフォルダーも、別のものを指定しない限り Radarr の最初のフォルダーを使用します。
ダウンロードとインデクサー

ツール	機能
manage_stalled_downloads	AUDIT は、停止または速度の遅い qBittorrent のダウンロードをハッシュとともに一覧表示します。PURGE_STALLED は、ハッシュを指定した項目とそのファイルのみを削除します。
check_indexer_health	障害発生中、バックオフ中、無効になっている Prowlarr インデクサーと、Prowlarr 自体の警告を報告します。

バックグラウンドジョブ

ツール	機能
plan_media_upgrade	ファイルがない、または解像度が 1080p 未満の映画を検索し、バッチジョブとしてスケジュールします（映画のみ。デフォルトでは一度に最大 25 件）。
get_background_jobs	ジョブとその進捗を一覧表示します。
update_job_status	ジョブを PAUSE、RESUME、または CANCEL します。ジョブを開始するには、再開する必要があります。
execute_next_job_step	ジョブ内の次の映画を手動で検索します。開始済みのジョブも、ジョブランナーによって 1 分に 1 件、自動的に進められます。

インフラストラクチャと分析

ツール	機能
get_cluster_infrastructure_health	各 SSH ホストの CPU、メモリ、Docker コンテナの状態を確認します。
get_cluster_hardware_analytics	ホストごとの CPU とメモリを表形式で表示します。
trust_new_host_key	監視対象のホストを再構築した後、記憶されている SSH キーを削除します。次回の確認時に、現在提示されているキーが信頼されます。ダッシュボードの 新しいキーを信頼 ボタンでも同じ操作を行えますが、WEB_PASSWORD が設定されている場合に限ります。
run_cluster_backup	Radarr、Sonarr、Prowlarr（設定されているもの）に組み込みのデータベースバックアップを実行させ、それぞれの完了を待ちます（最大で約 1 分。時間がかかるものは実行中として報告されます）。さらに、新しいバックアップファイルが作成されたことを、名前、サイズ、時刻とともに確認します。バックアップは各アプリ固有のバックアップフォルダーに保存され、コピーは行われません。
get_plex_activity	Tautulli 経由で、再生中のストリームとトランスコード負荷を確認します。
get_library_analytics	Tautulli 経由で、視聴回数の多い作品、上位ユーザー、プラットフォーム、ライブラリを確認します。

バッチジョブの仕組み。 plan_media_upgrade はジョブを PENDING 状態で作成します。RESUME するまで処理は実行されません。開始済みのジョブはジョブランナーによって、インターバルごとに Radarr の検索を 1 件ずつ実行します（デフォルトは 60 秒）。そのため、大量のバッチによってインデクサーに負荷が集中することはありません。一時停止、キャンセル、または保留中のジョブには一切手を加えません。また、ジョブが連続で 3 回失敗した場合（たとえば Radarr が停止している場合）、一時停止して Discord に報告します。

セキュリティ

• 信頼できるネットワーク上で実行してください。 自宅のLAN向けに設計されており、パブリックインターネットへの公開は想定もテストもされていません。外部からアクセスする場合は、信頼できるHTTPSとリバースプロキシの背後に配置してください。脆弱性の報告については、SECURITY.mdをご覧ください。
• WEB_PASSWORDを設定してください。 設定しない場合、ポートにアクセスできる人なら誰でもダッシュボードを利用し、設定を変更できます。
• シークレットはサーバー上に保持されます。 設定ページで保存済みのキーやトークンが返されることはありません。また、Plexのアートワークはサーバー側のプロキシ経由で取得されるため、Plexトークンがブラウザーに渡ることはありません。
• SSHホストの監視には鍵認証を使用し、各ホストの鍵を初回使用時に記憶します。 ホストが初めて接続すると、その鍵のフィンガープリントが保存されます。それ以降、別の鍵はコマンドが送信される前に拒否されます。その場合、Node Utilizationページではホストがオフラインとして表示され、正当に再構築したときに使える新しい鍵を信頼ボタンが表示されます（このボタンにはWEB_PASSWORDが必要です。設定していない場合は、Claude Desktopにtrust_new_host_keyを使用するよう依頼してください）。パスワードを設定していないと、ネットワーク上の誰でもこのボタンを使って偽装ホストを信頼させることができるため、パスワードが設定されている場合のみ表示されます。これにより、初回接続後にホストが偽装ホストに置き換えられるのを防ぎます。初回接続の確実性を確認したい場合は、フィンガープリントをssh-keyscan -t ed25519 <host> | ssh-keygen -lf -と照合してください。専用の非特権ユーザーを使用し、信頼できるネットワーク上で運用してください。
• 一部のツールは変更を加えます。 confirm_selected_choicesは映画を追加してダウンロードを開始します。PURGE_STALLEDを指定したmanage_stalled_downloadsは、AUDIT後に同意したトレントとそのファイルを削除します。また、ジョブランナーは検索を実行します。Claude Desktopはツールを使用する前に許可を求めるため、提案内容を確認してください。
• イメージはroot以外のユーザー（UID 65532）として実行されます。さらに制限する方法については、読み取り専用およびroot以外での運用をご覧ください。

開発

npm install
npm start           # MCP server (stdio) + dashboard on WEB_PORT
npm test            # the test suite
npx tsc --noEmit    # typecheck the backend and the tests

ダッシュボードは、web/にある独立したnpmプロジェクトです（React、Vite、TypeScriptを使用し、独自のpackage.jsonを備えています）。

cd web
npm install
npm run dev         # dev server on :5173, proxies /api to the backend on :3000
npx tsc --noEmit
npm run build       # static assets the backend serves; the Dockerfile does this for you

テストにはNode組み込みのテストランナーを使用するため、追加のインストールは不要です。テストは一時的なデータベースを使用し、実際の.envは読み込みません。環境からサービスの認証情報を取り除き、テストでモックを設定しない限り、すべてのHTTPリクエストを失敗させます。そのため、テストを実行しても実際のサービスに影響することはありません。test/isolation.test.tsは、これらの隔離措置のいずれかが破られるとテストを失敗させます。

実行時の注意事項

• 状態（設定、ジョブ履歴、ログインシークレット）は、SQLiteデータベースdata/plex_director.db（コンテナー内では/app/data）に保存されます。
• 公式のMCP SDKを使用します。
• Queryチャットは上記のツールとともにAnthropic APIを呼び出します。TMDbへの呼び出しと、設定した場合のDiscordへの呼び出しを除き、ネットワークの外に送信されるものはありません。

CI/CD

.github/workflows/ci.yml には、3 つのジョブがあります。

• 型チェックと監査（check）は、main に対するすべてのプッシュとプルリクエストで実行されます。TypeScript の型チェック、テストスイート、npm audit --audit-level=high に加えて、web/ のダッシュボードでも同じ型チェックと監査を実行します。
• ビルド、スモークテスト、公開（publish）は、main へのすべてのプッシュ、すべての v*.*.* タグのプッシュ、およびすべてのプルリクエストで、check の成功後に実行されます。毎回イメージをビルドし、ダミー設定で起動して、正常に開始することを確認します。プッシュの場合は、両方のレジストリに公開します（ブランチへのプッシュでは latest とコミット SHA のタグを付け、タグへのプッシュではバージョンも付けます。例：1.2.3 と 1.2）。さらに、Docker Scout の脆弱性スキャンを実行し（ジョブのサマリーに報告されます。現時点ではブロック要件ではありません）、cosign で両方のイメージに署名します。
• GitHub リリースの作成（release）は、v*.*.* タグのプッシュ時のみ、publish の成功後に実行され、生成されたリリースノートを含むリリースを作成します。

あわせて、CodeQL はすべてのプッシュとプルリクエスト時、および毎週 TypeScript を解析します。OpenSSF Scorecard は毎週、リポジトリのサプライチェーンの取り組みを評価します（上記のバッジを参照）。また Dependabot は npm、Docker のベースイメージ、GitHub Actions の更新に関するプルリクエストを毎週作成し、メジャーバージョンの更新を除き、CI が成功すると自動的にマージします。

ライセンス

MIT