plex-mcp

· claude-opus-4-8[1m] · 2026-07-07 · 詳細

MCP サーバー（Plex Media Server 向け）で、Docker コンテナとしてパッケージされています。MCP クライアント（Claude Desktop など）が Plex ライブラリを閲覧・検索できるようにします。

ツール

Related MCP server: Plex Assistant MCP

設定

必要な環境変数は次の2つです（両方必須）：

Plexトークンを確認するには、PlexのFinding an authentication tokenガイドを参照してください。

省略可能な環境変数

すべてに実用的なデフォルト値があります。上書きする場合のみ設定してください。

LOG_LEVEL、MCP_ALLOWED_HOSTS/MCP_ALLOWED_ORIGINS、HOST_IMAGE_DIR/HOST_LOG_DIR については、それぞれ1行の注記では済まないため、以下の各セクション（ロギング、HTTPトランスポートの堅牢化、Portainerデプロイ）で説明します。

コンテナと同じホスト上でPlexを実行していますか？ PLEX_URL=http://host.docker.internal:32400 を使用してください。composeファイルは extra_hosts を介して host.docker.internal をDockerホストのゲートウェイにマッピングするため、コンテナはホスト上で実行されているPlexサーバーに到達できます。そのマッピングがないと、ホスト自身のホスト名（例：my-nas）はコンテナ内部から解決されません。

トランスポートモード

HTTPモードでは、サーバーは次を公開します：

• POST/GET/DELETE /mcp — MCP Streamable HTTP エンドポイント（仕様準拠）

• GET /health — 生存確認プローブ（docker ヘルスチェックで使用）

HTTPモードには呼び出し元の認証がありません — TLS（後述）はトラフィックを暗号化しますが、呼び出し元を特定しません。プライベートネットワークにのみバインドしてください。ホストのファイアウォールまたはLAN分離に依存してください。事前にベアラートークン認証を追加せずにパブリックインターネットに公開しないでください。

HTTPSの有効化

HTTPSはオプトインです。起動時の解決順序：

1. Bring-your-own cert（独自証明書） — MCP_TLS_CERT_FILE と MCP_TLS_KEY_FILE の両方をPEMファイルのパスに設定します。Let's Encrypt や内部CAで終端する場合に使用します。サーバーは起動時にこれらを読み取ります。更新されたファイルを反映するにはコンテナを再起動してください。

2. Self-managed cert（自己管理証明書）（LAN専用セットアップに推奨） — MCP_TLS=auto を設定します。サーバーは初回起動時にECDSA P-256自己署名証明書を生成し、MCP_TLS_DIR（デフォルト /data/certs）に書き込み、以降の起動で再利用します。証明書の期限が30日以内になると自動的に再生成されます。

3. それ以外の場合、サーバーは平文HTTPのままです（現在のデフォルト）。

起動時にサーバーは証明書のSHA-256フィンガープリントと notAfter をログに記録します。フィンガープリントをクライアント側でピン留めするか、ブラウザやCLIツールのためにOSのキーストアで証明書を信頼してください。

TLSが有効な場合、composeのヘルスチェックには --no-check-certificate フラグが必要です — test: 行を ["CMD", "wget", "--no-check-certificate", "-q", "-O-", "https://localhost:3000/health"] に更新してください。

mcp-remote をHTTPSエンドポイントに向ける

自己署名証明書の場合、Node.jsのCAバンドルを介して証明書ファイルをピン留めするか、クライアント側で検証をスキップしてください（LANのみ）：

# Trust the server's self-signed cert (preferred):
NODE_EXTRA_CA_CERTS=./server.crt \
  npx -y mcp-remote https://nas.local:3443/mcp

# Or skip verification for quick testing (LAN-only):
NODE_TLS_REJECT_UNAUTHORIZED=0 \
  npx -y mcp-remote https://nas.local:3443/mcp

リバースプロキシの代替案

プロセス内TLSは、イングレスコントローラをまだ実行していない場合に便利です。自宅のサービスの前面にCaddy、Traefik、nginxを置いているなら、より自然なパターンはプロキシでTLSを終端し（Let's Encryptの自動化付き）、その背後で plex-mcp を平文HTTPのままにすることです。この2つのアプローチは交換可能です — 既存のセットアップに合う方を選んでください。

OAuth 2.1 ベアラートークン認証（オプトイン、現時点では実用不可）

コード側ではOAuth 2.1保護リソース認証のサポートが存在します（ChatGPT Apps SDK アライメント Phase 2 — 詳細な計画は docs/CHATGPT-APPS-SDK.md を参照）。しかし、まだ実際にオンにして使えるものではありません。トークンを発行する本物のOAuth 2.1アイデンティティプロバイダが必要ですが、このデプロイ用にはプロビジョニングされていません（それはフェーズ3で、未開始です）。ここでは完全性のために文書化されており、ハウツーとしては提供されていません。

有効にすると、すべての /mcp リクエストには Authorization: Bearer <jwt> が必要です — 設定されたIdPによって発行され、正しいオーディエンスとスコープを持つトークンです。/health は影響を受けません（別ルートであり、Docker自身のヘルスチェックにはベアラートークンを添付する方法がないため）。/.well-known/oauth-protected-resource はRFC 9728に従って自動的に提供されます。

Dockerで実行する（stdio、オンデマンド）

docker build -t plex-mcp .
docker run -i --rm \
  -e PLEX_URL=http://192.168.1.50:32400 \
  -e PLEX_TOKEN=your-token \
  plex-mcp

Docker Composeで実行する（HTTP、長期稼働）

composeファイルは ghcr.io/carldog/plex-mcp:latest をプルします（マルチアーキテクチャ: linux/amd64 + linux/arm64）。これは main へのプッシュのたびにCIによって公開されます。

# Required env vars (or use a .env file):
export PLEX_URL=http://192.168.1.50:32400
export PLEX_TOKEN=your-token
export MCP_ALLOWED_HOSTS=nas.local:3001  # required — see below
export HOST_PORT=3001  # optional, defaults to 3001

docker compose up

MCPエンドポイントは http://<host>:${HOST_PORT}/mcp になります。

プルする代わりにソースからリビルドするには：

docker build -t ghcr.io/carldog/plex-mcp:latest .
docker compose up

Portainerでデプロイする（Gitからのスタック）

1. Portainerで、Stacks → Add Stack → Repository を選択します。

2. リポジトリURL: https://github.com/CarlDog/plex-mcp

3. Composeパス: docker-compose.yml

4. 環境変数: PLEX_URL、PLEX_TOKEN、MCP_ALLOWED_HOSTS、HOST_IMAGE_DIR、HOST_LOG_DIR を設定します — すべて必須（下記参照）。任意で HOST_PORT。

5. デプロイします。ヘルスチェックは約10秒以内に緑になります。

HTTPモードでは MCP_ALLOWED_HOSTS が必須

サーバーが /mcp で受け付ける Host ヘッダー値のカンマ区切りリスト — 例: nas.local:3001（クライアントが実際に接続するホスト:ポート（マッピングされた HOST_PORT を含む）と一致する必要があります）。これがないとHTTPモードではサーバーは起動を拒否し、docker compose config も未設定の場合は同じように失敗します — どちらも、コンテナが起動する前に意図的に失敗し、無言で保護されていない状態で起動することはありません。

これは、コンテナ内で 0.0.0.0 にバインドすることが、ベアホスト上のループバックバインドのような実際のアクセス境界ではないためです：LAN上の任意の場所のブラウザで読み込まれたページは、DNSリバインディングを実行できます — 自身のホスト名をこのコンテナのIPに向ける — そして、混乱した代理人（confused deputy）としてツール（plex_delete_playlist のような書き込みを含む）を操作し、「LANのみ・ベアラートークンなし」というセキュリティ体制を完全に迂回します。Host許可リストは、完全な認証を必要とせずにこのギャップを埋めます。MCP_ALLOWED_ORIGINS（オプション、デフォルト空）は Origin ヘッダーに対して同じことを行います — ブラウザベースのクライアントが正当にこのサーバーを直接呼び出す必要がない限り、未設定のままにしてください。ブラウザ以外のクライアント（mcp-remote ブリッジ、直接の fetch）は Origin ヘッダーを送信しないため、空のデフォルトはDNSリバインディング攻撃が実際に送信するリクエスト形状のみを拒否します。

HOST_IMAGE_DIR と HOST_LOG_DIR は必須 — 相対パスのデフォルトはありません

両方のボリュームのホストパスはcomposeファイル内で ${VAR:?...} になっています：フォールバックのデフォルトはありません。そのため、どちらかが未設定の場合、壊れた状態で起動する代わりに、docker compose up / Portainerの再デプロイは明確なエラーで即座に失敗します。

これは以前はソフトな ${VAR:-./data/images} デフォルトでしたが、安定したクローンからのローカルな docker compose up でのみ安全です。Portainerのgitスタックでは罠になります：再デプロイのたびにリポジトリがコミットごとの新しいディレクトリ（/data/compose/<stack-id>/<commit>/）にクローンされ、そこには ./data/images のような相対パスは存在しません。Dockerはバインドマウントを拒否し、コンテナは created 状態のまま立ち往生しました — 起動しませんでした。これは 自動 再デプロイ（イメージ更新、gitポーリング）にも影響し、以前は正常だったスタックが手動操作なしでダウンしました。唯一の症状はコンテナが created のままだったことです。このため、2026-07-31にデプロイ済みスタックが約10時間ダウンしました — docker-deployments.md のルール#10とフリートレッスン 2026-07-31-relative-compose-volume-defaults-break-portainer-git-stacks を参照してください。composeファイルは現在、この要件をドキュメントのみの慣習ではなく構造的なものにしています。

スタックの環境変数で、両方を絶対ホストパスに設定してください：

• HOST_IMAGE_DIR — plex_save_image の出力ディレクトリです。 推奨: filesystem-mcp の /media/_mcp-scratch マウント元となるホストディレクトリ（例: Synology NAS では /volume1/Media/_mcp-scratch）。これにより plex_search → plex_save_image → filesystem-mcp のパイプラインを 1 つの共有ディレクトリにまとめられます。

• HOST_LOG_DIR — plex_download_logs の出力ディレクトリです。診断用 ZIP はメディア成果物ではないため、HOST_IMAGE_DIR とは分離して保持します（例: Synology NAS では /volume1/docker/plex-mcp/logs。この環境群のコンテナごとの appdata 規約に合わせています）。

両方のディレクトリは、最初のデプロイの前にホスト上に存在することを確認してください。Docker は存在しないバインドマウント元を自動生成せず、単にコンテナの起動を拒否します。

Claude Desktop での使用

stdio（ローカル呼び出し）

{
  "mcpServers": {
    "plex": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "PLEX_URL", "-e", "PLEX_TOKEN",
        "plex-mcp"
      ],
      "env": {
        "PLEX_URL": "http://192.168.1.50:32400",
        "PLEX_TOKEN": "your-token"
      }
    }
  }
}

HTTP（リモート MCP サーバー）

{
  "mcpServers": {
    "plex": {
      "url": "http://nas.local:3001/mcp"
    }
  }
}

（Claude Desktop、またはリモート MCP HTTP に対応したクライアントが必要です。）

ローカル開発

npm install
cp .env.example .env  # then edit
PLEX_URL=... PLEX_TOKEN=... npm run dev               # stdio
MCP_PORT=3000 MCP_ALLOWED_HOSTS=localhost:3000 PLEX_URL=... PLEX_TOKEN=... npm run dev # HTTP

ログ

サーバーは構造化ログを stderr に出力します（stdout は stdio モードでの MCP ワイヤープロトコルであり、汚染してはいけません）。形式:

2026-04-29T15:30:00.000Z INFO [tool:plex_browse] invoke section_id=7 type=show limit=2
2026-04-29T15:30:00.337Z INFO [tool:plex_browse] ok ms=337

詳細度は LOG_LEVEL 環境変数で設定します（デフォルトは info）:

コンテナログは Docker の json-file ドライバーで収集され、自動的にローテーションされます（10MB × 3 ファイル = ~30MB 上限。ローテーション時に最も古いファイルが削除されます）。docker logs plex-mcp または docker logs -f で表示できます。

セキュリティ

• コンテナは非 root ユーザー（plexmcp）で実行されます。

• Plex トークンは環境変数経由で渡されます。イメージに焼き込まないでください。

• .githooks/pre-commit はすべてのコミットで gitleaks を実行します。クローンごとに一度有効化してください: git config core.hooksPath .githooks