Plex MCP Server

Plex MCP サーバー

Claude、ChatGPT、その他の MCP クライアントから Plex ライブラリ、メディア、再生を管理する MCP サーバーです。

機能

• JSON レスポンス：Plex の操作結果を構造化して返します。
• 複数のトランスポート：stdio、SSE（Server-Sent Events）、Streamable HTTP に対応しています。
• 包括的な制御：ライブラリ、メディア、コレクション、プレイリスト、クライアント、ユーザーを管理できます。
• リモート接続に対応：Claude.ai などのリモート AI プラットフォームとの統合に役立つ OAuth 2.1 を標準でサポートしています。
• 管理ツール：ログへのアクセス、帯域幅の監視、Butler タスクの実行ができます。

インストール

方法 1：uv を使用（推奨）

インストールせずに直接実行します：

uvx plex-mcp-server --transport stdio --plex-url http://your-server:32400 --plex-token your-token

方法 2：pip でインストール

pip install plex-mcp-server

方法 3：開発／ソースから

git clone https://github.com/vladimir-tutin/plex-mcp-server.git
cd plex-mcp-server
pip install -e .

方法 4：Docker

公開イメージは Linux の amd64 および arm64 向けの ghcr.io/vladimir-tutin/plex-mcp-server:latest です。root 以外のユーザーとして実行され、/mcp で Streamable HTTP、/sse で従来の SSE を提供します。Plex の API を使用するため、メディアフォルダーをマウントする必要はありません。

以下の Docker セットアップに従ってから、Claude.ai や ChatGPT などのホスト型クライアントについてはパブリック HTTPS アクセスを参照してください。

Docker Compose

git clone https://github.com/vladimir-tutin/plex-mcp-server.git
cd plex-mcp-server
cp .env.docker.example .env

起動前に .env を編集します。たとえば、信頼できる LAN にデプロイする場合は、次のようにします。

PLEX_URL=http://192.168.1.10:32400
PLEX_TOKEN=your-plex-token
MCP_BIND_ADDRESS=192.168.1.20
MCP_PUBLISHED_PORT=3001
MCP_SERVER_URL=http://192.168.1.20:3001
MCP_OAUTH_ENABLED=false

192.168.1.10 を Plex のアドレスに、192.168.1.20 を Docker ホストのアドレスに置き換えます。OAuth を使用しない場合、このポートにアクセスできる人は誰でもツールを使用できます。付属のサンプルファイルでは、Docker ホストからのみアクセスできるよう、デフォルトでループバック（127.0.0.1）に設定されています。.env は非公開にしてください。

docker compose pull
docker compose up -d --no-build
docker compose logs -f

LAN の例で使用するクライアント URL は http://192.168.1.20:3001/mcp です。ホスト型クライアントには、アクセス可能な HTTPS エンドポイントが必要です。パブリック HTTPS アクセスを参照してください。

その他の Docker デプロイ

ghcr.io/vladimir-tutin/plex-mcp-server:latest を使用し、コンテナーポート 3001（TCP）を公開して、以下の環境変数を設定します。

キー	設定例
PLEX_URL	http://192.168.1.10:32400
PLEX_TOKEN	your-plex-token
MCP_SERVER_URL	http://192.168.1.20:3001
MCP_TRANSPORT	streamable-http（デフォルト。/mcp と /sse の両方を提供）

MCP_SERVER_URL には、Docker ホストのアドレスと公開ポートを使用してください。MCP_BIND_ADDRESS と MCP_PUBLISHED_PORT は、このリポジトリの Compose ファイルの設定にのみ使用されます。それ以外のデプロイでは、ポートマッピングを直接設定してください。

公開 HTTPS アクセス

MCP_SERVER_URL を設定しても、DNS レコードの作成、HTTPS の設定、コンテナーの公開は行われません。ホスト型クライアントを接続する前に、以下の手順を完了してください。

1. リモートアクセスと OAuth を使用して OAuth プロバイダーを作成します。

2. Compose の .env またはコンテナーの環境に、以下の値を設定します。

   MCP_SERVER_URL=https://plexmcp.example.com
   MCP_OAUTH_ENABLED=true
   MCP_OAUTH_ISSUER=https://auth.example.com/application/o/plexmcp-oauth/
   MCP_OAUTH_AUDIENCE=your-oauth-client-id
   

   上記のとおり、PLEX_URL と PLEX_TOKEN も設定したままにしてください。これらは OAuth 認証情報とは別です。MCP_SERVER_URL は、/mcp や /sse を含まない公開 ベース URL です。MCP_OAUTH_ISSUER は、パスと末尾のスラッシュを含む、プロバイダーの正確な発行者 URL です。

3. 公開ホスト名をリバースプロキシに向け、有効な HTTPS 証明書を設定します。そのホスト名から、公開された MCP コンテナーのアドレス（例：http://192.168.1.20:3001）に転送します。これは Docker ホストと ホストポート であり、Plex のポート 32400 や Authentik のアドレスではありません。

4. そのホスト名へのすべてのパスを変更せずに転送し、公開 Host ヘッダーと Authorization ヘッダーを保持し、バッファリングせずにストリーミング応答を許可します。Compose を使用する場合は、公開アドレスにプロキシが到達できる必要があります。プロキシが別の場所で実行されている場合は、Docker ホストの LAN アドレスを使用してください。別のコンテナー内のプロキシは、このコンテナーに自身の 127.0.0.1 経由で到達できません。

5. プロキシでブラウザーログインページを表示して遮断するのではなく、リクエストが MCP サーバーの OAuth ミドルウェアに到達するようにします。対象には /mcp、/sse、/messages/、/.well-known/ のディスカバリーパス、/authorize、/token が含まれます。MCP サーバーはベアラートークンを検証し、Authentik は OAuth ログインを処理します。

6. 設定を更新してコンテナーを再作成します（Compose の場合は docker compose up -d --no-build）。クライアントには https://plexmcp.example.com/mcp（Streamable HTTP）または https://plexmcp.example.com/sse（レガシー SSE）を設定します。

OAuth が有効な場合、/mcp または /sse への未認証リクエストは 401 を返し、/.well-known/oauth-protected-resource は JSON を返します。プロキシのログインページや 502 が表示される場合、リクエストは想定される MCP ハンドラーに到達していません。最後に、クライアントからサインインし、Plex ライブラリの一覧を表示するように依頼します。

既存のデプロイを移行する場合は、リバースプロキシのアップストリームを新しいホストとポートに更新します。公開 MCP URL とクライアント URL はそのまま使用できます。OAuth プロバイダーも移動する場合は、その発行者 URL と設定を維持するか、MCP_OAUTH_ISSUER とクライアント認証情報を一致するように更新してください。

イメージの更新またはビルド

latest は公開済みリリースを追跡し、edge は main を追跡します。リリースを固定するには、1.2.0 のようなバージョンタグを使用します。実行中のコンテナーは自動的には更新されません。

Compose の場合は、以下のコマンドで更新します。

docker compose pull
docker compose up -d --no-build

ソースからビルドするには、docker compose build --pull を実行し、その後 docker compose up -d --no-build を実行します。

Compose を使わずに公開済みイメージを実行する場合は、上記のサーバー変数を含む .env を用意し、ホストのバインド先を明示的に指定します。

docker run -d --name plex-mcp-server --restart unless-stopped --init \
  --env-file .env -p 127.0.0.1:3001:3001 ghcr.io/vladimir-tutin/plex-mcp-server:latest

このコマンドはループバックインターフェイスでのみ公開します。スタンドアロンの SSE の場合は、--transport sse --host 0.0.0.0 --port 3001 を追加します。stdio の場合は、ポートを公開せずに docker run --rm -i --env-file .env ghcr.io/vladimir-tutin/plex-mcp-server:latest --transport stdio を使用します。

設定

コンテナーの場合は、Docker のセットアップを使用してください。以下のオプションは、Python を直接インストールする場合にも適用されます。PLEX_URL は Plex を指し、MCP_SERVER_URL はこの MCP サービスのアドレスです。コンテナー内では localhost はコンテナー自体を指すため、Plex には到達可能なネットワークアドレスを使用してください。

以下のいずれかの方法で、Plex サーバーの URL とトークンを設定します。

1. コマンドライン引数

plex-mcp-server --plex-url "http://192.168.1.10:32400" --plex-token "ABC123XYZ"

2. 環境変数（.env）

現在のディレクトリまたは ~/.config/plex-mcp-server/.env に .env ファイルを作成します。

PLEX_URL=http://localhost:32400
PLEX_TOKEN=your-authentication-token
MCP_OAUTH_ENABLED=false

OAuth の設定については、リモートアクセスと OAuth を参照してください。

3. MCP クライアントの設定

Claude Desktop の例（%APPDATA%/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "plex": {
      "command": "uvx",
      "args": [
        "plex-mcp-server",
        "--transport",
        "stdio",
        "--plex-url",
        "http://your-server:32400",
        "--plex-token",
        "your-token"
      ]
    }
  }
}

stdio のみをサポートするクライアントからのリモートサーバー接続

クライアントがローカルの stdio プロセスの起動にしか対応していない場合は、 mcp-remote を使用して、リモートの Plex MCP サーバーに接続します。クライアントマシンに Node.js（npx を提供します）をインストールし、次のように実行します。

{
  "mcpServers": {
    "plex": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://plexmcp.example.com/mcp"]
    }
  }
}

サーバーを --transport streamable-http で実行する場合は /mcp を使用します。SSE でデプロイする場合は、代わりに /sse を使用します。信頼できるプライベートネットワーク上で通常の HTTP を使用する場合は、 引数に "--allow-http" を追加します。OAuth が有効な場合は、必要なクライアント認証情報やコールバックの登録を含め、 ブリッジのOAuth 設定手順に従ってください。

ネイティブのリモート HTTP 接続に対応しているクライアントは、/mcp に直接接続できるため、 Node.js、npx、このブリッジは不要です。上記のローカル stdio の設定にもブリッジは不要です。

4. Claude コネクターのインストール

https://claude.ai/settings/connectors にアクセスし、次の設定で新しいコネクターを追加します。

• 名前：Plex MCP
• URL：SSE の場合は https://plexmcp.example.com/sse、--transport streamable-http で実行する場合は https://plexmcp.example.com/mcp。
• OAuth が有効な場合は、詳細設定にプロバイダーの Client ID と Client Secret を入力し、サインインを完了します。

OAuth プロバイダーに Claude のコールバックを登録します：https://claude.ai/api/mcp/auth_callback。 プロバイダーとリバースプロキシの設定については、リモートアクセスと OAuth を参照してください。

5. ChatGPT コネクターのインストール

--transport streamable-http でサーバーを起動し、パブリックな HTTPS URL からアクセスできるようにします。 ChatGPT のプラグイン設定で、カスタム MCP サーバーを追加を選択します。

• 名前：Plex MCP
• サーバー URL：https://plexmcp.example.com/mcp
• 認証：サーバーで有効になっている場合は OAuth、それ以外の場合は なし。
• OAuth クライアントが confidential の場合は、OAuth 詳細設定を開き、プロバイダーの Client ID と Client Secret を入力します。これらは Plex トークンとは別のものです。

スクリーンショットでは、サーバーで必要な場合に OAuth 設定を確認する場所を示しています。 例ではプレースホルダーのサーバー URL を使用しているため、検出に失敗します。実際の サーバー URL と、プロバイダーが必要とするトークンエンドポイントの認証方式を使用してください。

OAuth プロバイダーに ChatGPT の正確なコールバック URL を登録します。URL は https://chatgpt.com/connector/oauth/<callback-id> のような形式です。文字どおりのプレースホルダーではなく、 接続で要求される値を使用してください。プラグインを作成し、サインインを完了して、 ツールを更新します。ChatGPT に Plex ライブラリの一覧を表示するよう依頼して、動作を確認します。

リバースプロキシのルーティングについては、パブリック HTTPS アクセスを参照してください。

Web サイトのプラグインとローカルの Codex MCP エントリーは、別々の接続です。ローカルの Codex OAuth 設定については、クライアント設定手順を参照してください。

Streamable HTTP

--transport streamable-http を指定してサーバーを起動し、/mcp を公開します。

plex-mcp-server --transport streamable-http --port 3001 --server-url https://plexmcp.example.com

クライアントを https://plexmcp.example.com/mcp で設定します。このモードでは、既存のクライアント向けに従来の /sse および /messages/ エンドポイントも引き続き利用できます。 .env またはコンテナーの環境変数に MCP_TRANSPORT を設定し、streamable-http、sse、stdio のいずれかを選択します。明示的に指定した --transport フラグが優先されます。 Docker のデフォルトは streamable-http で、/mcp と従来の /sse の両方を提供します。 直接実行する場合、環境変数もフラグも指定されていなければ、デフォルトで sse が使用されます。 Docker で stdio を使用する場合、MCP クライアントは docker run --rm -i でコンテナーを起動する必要があります。ポートマッピングは不要です。

OAuth は、どちらの HTTP トランスポートでも任意です。--oauth-enabled または MCP_OAUTH_ENABLED=true で有効にし、以下の発行者設定を使用します。OAuth がなければ、エンドポイントにアクセスできる人は誰でもツールを呼び出せるため、適切なネットワーク境界を設けてください。

SSE と Streamable HTTP はどちらも、DNS リバインディング攻撃（悪意のある Web ページがブラウザーを介してサーバーを操作する攻撃）を防ぐために、Host ヘッダーと Origin ヘッダーを検証します。--server-url（または MCP_SERVER_URL）を設定すると、OAuth が無効でも公開ホスト名とオリジンが許可されます。追加のプロキシ名、LAN アドレス、ブラウザーのオリジンを許可するには、MCP_ALLOWED_HOSTS と MCP_ALLOWED_ORIGINS をカンマ区切りで設定します（例：MCP_ALLOWED_HOSTS=192.168.1.20:3001）。 ループバックホストはデフォルトで許可されます。リモートクライアントで 421 Invalid Host header が発生した場合は、そのホストとポートを MCP_ALLOWED_HOSTS に追加してください。ブラウザーのオリジンが拒否された場合は、オリジン全体（スキーム、ホスト、ポート）を MCP_ALLOWED_ORIGINS に追加してください。

リモートアクセスと OAuth

OAuth は、どちらの HTTP トランスポートも保護します。以下の設定例では、ID プロバイダーとして Authentik を使用します。

仕組み

MCP サーバーは OAuth の窓口として動作します。クライアントは /.well-known/oauth-protected-resource を通じてサーバーを検出し、/authorize に転送され（ID プロバイダーにリダイレクトされます）、/token でコードを交換します（サーバーがプロバイダーに中継します）。そのため、クライアントに必要なのは MCP サーバーの URL とプロバイダーの Client ID／Secret だけです。ブラウザーでプロバイダーにアクセスし、サインインを完了します。アクセストークンは JWT であり、プロバイダーの JWKS に照らして検証されます。サーバーは SSE と Streamable HTTP の両方で、すべてのリクエストに対して署名、有効期限、発行者、および（任意で）オーディエンスを確認します。

1. OAuth プロバイダーを作成する（Authentik の例）

1. Providers → Create → OAuth2/OpenID Provider. クライアントタイプは Confidential、署名鍵セットは RS256 に設定します。Client ID と Client Secret を控えておきます。

2. Redirect URIs — 使用予定のクライアントごとにエントリーを追加します。実際に使用される値は次のとおりです。

   クライアント	リダイレクト URI
   Claude.ai / Claude Desktop	https://claude.ai/api/mcp/auth_callback
   ChatGPT connector	https://chatgpt.com/connector/oauth/<connector-id> — コネクターのダイアログに表示されます
   Codex CLI / local tools	ループバック、ランダムポート：正規表現 ^http://127\.0\.0\.1:[0-9]+/callback/<callback-id>$

   このリストは必要最小限にしてください。.* のような全件一致パターンを設定すると、リンクをクリックさせることができる人なら誰でも、認可コードを取得できてしまいます。

3. Applications → Create を選択し、プロバイダーに紐付けて、アクセス ポリシーを紐付けます（ユーザーまたはグループ）。このアプリケーションを認可できる Authentik ユーザーは誰でも Plex を完全に操作できます。MCP サーバー内にユーザーごとのロールはありません。

4. プロバイダーの OpenID Configuration Issuer URL をコピーします（例：https://auth.example.com/application/o/plexmcp-oauth/。末尾のスラッシュを含みます）。

2. サーバーを設定する

Docker の場合は、公開 HTTPS の設定に従って環境変数を設定します。この設定では DNS とリバースプロキシについても説明しています。

MCP_OAUTH_ENABLED=true
MCP_OAUTH_ISSUER=https://auth.example.com/application/o/plexmcp-oauth/
MCP_SERVER_URL=https://plexmcp.example.com
MCP_OAUTH_AUDIENCE=<Client ID>        # optional, recommended

または、同等のフラグを指定します：--oauth-enabled --oauth-issuer … --server-url … --oauth-audience …。

• MCP_SERVER_URL には、クライアントが接続する公開 HTTPS URL を指定する必要があります。この URL は、DNS リバインディング保護で許可される Host／Origin にもなります。/mcp や /sse を付けないベース URL を使用してください。HTTPS はリバースプロキシによって提供されます。
• MCP_OAUTH_AUDIENCE を設定すると、同じプロバイダーの別のクライアント向けに発行されたトークンをサーバーが拒否します。手順 1 の Client ID を設定してください。未設定の場合は、既存のデプロイとの互換性を保つため、オーディエンス検証は無効になります。

3. 各クライアントを設定する

手順 1 の Client ID と Secret を使用し、次のいずれかの URL を指定します。

クライアント	URL	備考
Claude.ai / Claude Desktop	https://plexmcp.example.com/sse	Claude は最初に Streamable HTTP POST で接続を試み、自動的に SSE にフォールバックします
ChatGPT	https://plexmcp.example.com/mcp	認証：OAuth、Client ID／Secret を貼り付けます
Codex CLI	codex mcp add plex --url https://plexmcp.example.com/mcp --oauth-client-id <id> --oauth-client-secret <secret>	ログイン用にブラウザーを開きます

/mcp で設定されたクライアントは Streamable HTTP を使用し、/sse は従来のトランスポートを使用します。 どちらも同じ方法で保護されます。

ディスカバリーエンドポイント

OAuth が有効な場合、次の標準エンドポイントが認証なしで公開されます。

• /.well-known/oauth-protected-resource
• /.well-known/oauth-authorization-server
• /authorize（プロバイダーにリダイレクト）と /token（プロバイダーにプロキシ）

コマンドリファレンス

ライブラリモジュール

Plex ライブラリの参照と管理に使用するツールです。

コマンド	説明	パラメーター
library_list	利用可能なすべてのライブラリを一覧表示します。	なし
library_get_stats	ライブラリの統計情報（件数、サイズ、種類）を取得します。	library_name
library_refresh	ライブラリのメタデータ更新を開始します。	library_name
library_scan	ライブラリをスキャンして新しいファイルを検出します。	library_name
library_get_details	ライブラリの詳細情報を取得します。	library_name
library_get_recently_added	ライブラリに最近追加された項目を一覧表示します。	library_name、limit: int
library_get_contents	現在のライブラリ項目をメディア ID、フィルター、ページネーションとともに一覧表示します。	library_name（省略可）、media_type、watched: bool、unwatched: bool、offset: int、limit: int、sort、title、genre、year、content_rating、director、actor、writer、resolution、network、studio、username

再生履歴ではなく、現在ライブラリにある視聴済み映画を一覧表示するには、次のようにします。

{"library_name": "Movies", "watched": true, "offset": 0, "limit": 50}

各結果には、その項目を検索または削除するための media_id（Plex の ratingKey）が含まれます。デフォルトのページサイズは 50 です。後続のページを取得するには offset を増やしてください。 totalItems は、現在のページだけでなく、サーバー側のフィルターに一致する件数です。 title を使用すると、大文字と小文字を区別しない Plex のタイトル検索を他のフィルターと組み合わせられます。 {"library_name":"Movies","title":"Avengers","watched":true}。 これは通常のページネーションで一致するすべての項目を返します。完全一致のみの検索や任意の部分文字列検索ではありません。Avengers はその語を含むタイトルに一致しますが、venger は一致しません。タイトル検索では選択したメディアタイプが使用されます。TV ライブラリでは、デフォルトで番組名が検索されます。 視聴状態は、選択した username に属します。省略した場合は、設定済みのアカウントが使用されます。

アクセス可能なすべてのライブラリを横断して検索するには、library_name を省略し、media_type を指定します。

{"media_type":"movie","watched":true,"genre":"Action"}

サポートされているタイプは movie、show、episode、artist、album、track です。 TV ライブラリ内の episode や音楽ライブラリ内の track など、名前付きライブラリ内でタイプを選択することもできます。タイプを選択した検索結果には、元の library と library_id が含まれます。エピソードには番組／シーズン／エピソード、トラックにはアーティスト／アルバムの情報が含まれます。 フィルターと並べ替えは、結合された結果に対してページネーションの前に適用されます。library_name または media_type のいずれかを指定する必要があります。大規模なライブラリでは、範囲の広いエピソード検索に時間がかかる場合があります。ライブラリまたはタイトルのフィルターを指定すると、検索範囲を絞り込めます。

音楽では、watched／unwatched によって再生済み／未再生の項目を選択します。アーティストやアルバムの再生状態は、すべてのトラックが再生済みであることを意味しません。

映画、エピソード、トラックの結果には、Plex に保存された再生位置に基づく inProgress と progressPercent も含まれます。映画が［視聴を続ける］に表示されていなくても同様です。 inProgress は、その再生位置が 0 より大きい場合に true になります。これは映画が現在再生中であることを意味するものではありません。progressPercent は保存された再生位置を再生時間に対する割合で表したもので、小数第 1 位に丸められ、0～100 の範囲に収まります（再生時間が不明な場合は null）。 再生位置が保存されていない映画は、以前に視聴済みであっても inProgress: false となり、再生時間がわかっている場合は progressPercent: 0 になります。

これらのフィールドは watched とは独立しています。たとえば、再視聴中の映画は視聴済みであり、かつ再生中の場合があります。watched フィルターと unwatched フィルターは、保存された再生位置ではなく、引き続き Plex の視聴状態を使用します。整理の際、保存された再生位置のある映画を誤って選択しないよう、watched と併せて inProgress も確認してください。

番組では、watched=true にすると未視聴エピソードのないシリーズが選択されます。unwatched=true にすると、部分的に視聴されたシリーズを含む、未視聴エピソードが残っているシリーズが選択されます。結果には watchStatus（unwatched、partial、watched のいずれか）、watchedEpisodeCount、episodeCount が含まれます。視聴完了の判定対象は、将来のエピソードや欠落しているエピソードではなく、現在ライブラリにあるエピソードです。エピソードがない番組は watched=false になります。両方のフィルターを true に設定しないでください。

フィルターは選択したメディアタイプに適用できるものである必要があります。サポートされていない組み合わせは、無視されるのではなくエラーを返します。エピソードのジャンル、レーティング、人物、ネットワーク、スタジオの各フィルターは親番組を使用します。トラックの年とスタジオは親アルバムを使用します。アーティストのフィルターではタイトルとジャンルがサポートされています。アルバムとトラックでは、年とスタジオもサポートされています。 解像度は映画とエピソードに適用されます（sd、480、576、720、1080、2k、4k、8k）。

メディアモジュール

特定のメディアアイテムを検索、確認、編集するためのツールです。

コマンド	説明	パラメーター
media_search	すべてのライブラリからメディアを検索します。	query、library_name、content_type
media_get_details	アイテムの詳細情報を取得します。	media_title、library_name、media_id、username
media_set_watched_status	アイテムを視聴済みまたは未視聴に設定します。番組、シーズン、アルバム、アーティストに適用すると、一部だけ視聴済みのエピソードやトラックも含め、すべてのエピソードまたはトラックに適用されます。	media_id、watched、username
media_edit_metadata	タグ、ジャンル、概要、タイトルを更新します。	media_title、library_name、new_title、new_summary、new_rating、new_release_date、new_genre、remove_genre、new_director、new_studio、new_tags
media_delete	Plex からアイテムを削除します。	media_title、library_name、media_id、username
media_get_artwork	ポスターまたは背景アートワークを取得します。	media_title、library_name、art_type: str
media_set_artwork	ローカルパスまたは URL からアートワークを設定します。	media_title、library_name、poster_path、poster_url、background_path、background_url
media_list_available_artwork	選択可能な代替アートワークを一覧表示します。	media_title、library_name、art_type

library_get_contents、media_get_details、media_set_watched_status は、設定済みの管理者認証情報を使用して、ホームユーザーまたは共有ユーザーを指定する username を受け付けます。自分のアカウントの場合は省略してください。 視聴済みフィルターと保存された再生位置は、選択したユーザーに紐づきます。アクセスに失敗するとエラーが返されます。映画、エピソード、トラックの詳細には、watched、view_count、playback_offset_ms、in_progress、progress_percent が含まれます。番組、シーズン、アルバム、アーティストの詳細には、watched、watch_status（watched、partial、unwatched）、watched_count、total_count が含まれます。

ウォッチリストモジュール

Plex アカウントのウォッチリストを管理します。ライブラリにない映画や番組も対象です。 一覧と検索結果には、Plex から提供される場合、追加の照会なしで release_date、duration_ms（ミリ秒単位の再生時間）、content_rating が含まれます。 公開日は、劇場公開、パッケージ版の発売、ストリーミング配信を区別しません。

デフォルトでは、一覧表示時に選択したユーザーのライブラリ状態も照会します。映画には保存済みの再生位置と視聴済み状態が含まれ、番組には視聴済みエピソード数と全エピソード数が含まれます。一致判定では、まず Plex GUID を使用し、次にタイトルで検索して、IMDb、TMDB、TVDB のいずれかの ID が一致することを確認します。一致したライブラリ内の各項目は library_items に返されます。一致しない項目の利用可能状況は不明（null）であり、未視聴状態を示すものではありません。照会に失敗しても、ウォッチリストは state_error とともに利用できます。ライブラリの照会を省略するには、include_state=false を設定します。個々のエピソードの再生状況は含まれません。

コマンド	説明	パラメーター
watchlist_list	利用可能状況と視聴済み／再生状況を含めて、ウォッチリストのタイトルを一覧表示します。	offset、limit（1～100）、include_state（デフォルトは true）
watchlist_search	追加するタイトルを Plex Discover で検索します。	query、content_type（movie/show）、limit（1～100）
watchlist_add	映画または番組を追加します。	guid
watchlist_remove	映画または番組を削除します。	guid

まず検索し、選んだ結果の guid を watchlist_add に渡します。項目を削除するには、watchlist_list で取得した GUID を使用します。これらの plex://movie/... または plex://show/... 識別子はクラウド ID であり、ローカルの media_id／ratingKey 値ではありません。 一覧表示の結果はデフォルトで 50 項目です。次のページを取得するには offset を増やします。

4 つのツールすべてで、設定済みの PLEX_TOKEN を使用します。ユーザーを正確なユーザー名またはプロフィールタイトルで選択するには username を、ID で選択するには home_user_id を渡します（こちらが優先されます）。Plex から PIN を求められる場合は、pin を指定してください。Plex がそのユーザーのウォッチリストにアクセスできない場合、ツールはエラーを返し、自分のウォッチリストにはフォールバックしません。セレクターを省略すると、設定済みのアカウントが使用されます。 追加／削除操作では所属を確認し、メディアファイルと視聴済み状態は変更しません。

プレイリストモジュール

個人用および共有プレイリストを管理します。

コマンド	説明	パラメーター
playlist_list	プレイリストを一覧表示します。	library_name、content_type、username
playlist_get_contents	プレイリストの項目を一覧表示します。	playlist_title、playlist_id、username
playlist_create	プレイリストを作成します。	playlist_title、item_titles、library_name、summary、username
playlist_delete	プレイリストを削除します。	playlist_title、playlist_id、username
playlist_add_to	メディア項目を追加します。	playlist_title、playlist_id、item_titles、item_ids、username
playlist_remove_from	プレイリストの項目を削除します。	playlist_title、playlist_id、item_titles、username
playlist_edit	タイトルまたは概要を変更します。	playlist_title、playlist_id、new_title、new_summary、username
playlist_upload_poster	ポスターをアップロードします。	playlist_title、playlist_id、poster_url、poster_filepath、username
playlist_copy_to_user	プレイリストを別のユーザーにコピーします。	playlist_title、playlist_id、username、source_username

設定済みの管理者認証情報を使用してホームユーザーまたは共有ユーザーのプレイリストを操作するには、username を渡します。省略すると、設定済みのアカウントが使用されます。アクセスに失敗するとエラーが返されます。playlist_copy_to_user では、username がコピー先です。source_username でコピー元のアカウントを選択し、省略すると設定済みのアカウントが使用されます。

スマートプレイリスト

スマートプレイリストでは、ライブラリの変更に応じて Plex が再適用するライブラリフィルターを保存できます。 3 つのツールすべてで、ホームユーザーおよび共有ユーザーを含む username を指定できます。

ツール	目的
playlist_get_smart_filter_options	library_name と任意の libtype に対応するフィールド、演算子、並べ替え、フィールド値を確認します。
playlist_create_smart	filters、sort、limit、libtype をプレイリストとして保存します。
playlist_edit_smart_filters	省略された設定を保持しながら、ID またはタイトルでプレイリストを更新します。

番組に一致させるには、libtype="show" と {"title": "Band of Brothers"} を使用します。 エピソードのタイトルに一致させるには、libtype="episode" を使用します。番組名やアーティスト名で検索すると、 再生可能なエピソードやトラックが返されます。フィルターの確認時にも同じ libtype を使用してください。

作成および編集では、保存された definition、項目数、最大 20 件の項目が返されます。 playlist_get_contents は、現在のすべての項目と保存された定義を返します。 編集時に省略した値は変更されません。{} はフィルターをクリアし、空の sort 文字列は並べ替えをクリアし、 limit=0 は上限を解除します。libtype は指定した場合のみ変更されます。

コレクションモジュール

映画や番組をコレクションに整理します。

コマンド	説明	パラメーター
collection_list	指定したライブラリ内のコレクションを一覧表示します。	library_name
collection_create	新しいコレクションを作成します。	library_name、title、items: List[str]
collection_add_to	既存のコレクションに項目を追加します。	library_name、collection_title、items: List[str]、collection_id
collection_remove_from	コレクションから項目を削除します。	library_name、collection_title、items: List[str]、collection_id
collection_edit	コレクションのメタデータと設定を編集します。	collection_title、collection_id、library_name、new_title、new_sort_title、new_summary、new_content_rating、new_labels、add_labels、remove_labels、poster_path、poster_url、background_path、background_url、new_advanced_settings
collection_delete	コレクションを削除します。	collection_title、collection_id、library_name

ユーザーモジュール

サーバー所有者と共有ユーザーに関する情報です。

コマンド	説明	パラメーター
user_search_users	共有ユーザーを検索します。	search_term
user_list_all_users	種類と ID を含むすべてのユーザーを一覧表示します。	なし
user_get_info	特定のユーザーの詳細情報を取得します。	username
user_get_on_deck	ユーザーの「オンデッキ」項目を取得します。	username
user_get_continue_watching	続きから再生できる、視聴途中の項目を取得します。	limit、username、user_id
user_get_watch_history	個人の視聴履歴を取得します。	username、limit、content_type、user_id
user_get_statistics	視聴の進捗状況と利用統計を取得します。	time_period、username

user_get_continue_watching では、完全一致するユーザー名またはプロフィールタイトル、あるいは user_list_all_users の user_id を指定できます。ID が優先されます。どちらも省略すると、設定済みアカウントが使用されます。他のユーザーへのアクセスにはサーバー管理者のトークンが必要で、この Plex サーバー内に限定されます。アクセスに失敗すると、エラーが返されます。

セッションモジュール

サーバーのリアルタイムのアクティビティを監視します。

コマンド	説明	パラメーター
sessions_get_active	現在再生中の項目とクライアントを取得します。	なし
sessions_get_media_playback_history	特定のメディア項目の履歴を取得します。	media_title、library_name、media_id、username

Server Module

メンテナンスおよび管理用ツールです。

コマンド	説明	パラメーター
server_get_plex_logs	Plex ログから行を取得します。	num_lines、log_type、start_line、list_files、search_term
server_get_info	サーバーの基本的な稼働状態とバージョン情報です。	なし
server_get_bandwidth	帯域幅の使用統計です。	timespan、lan
server_get_current_resources	ホスト／プロセスの CPU／メモリ使用量です。	なし
server_get_butler_tasks	スケジュールされたメンテナンスタスクを一覧表示します。	なし
server_get_alerts	サーバーの通知／アラートを受信します。	timeout
server_run_butler_task	Butler タスクを手動で実行します。	task_name
server_empty_trash	ライブラリのゴミ箱を空にします。	library_name
server_optimize_database	データベースの最適化を実行します。	なし
server_clean_bundles	使用されていないメディアバンドルをクリーンアップします。	なし

Client Module

Plex クライアントでの再生とナビゲーションを制御します。

コマンド	説明	パラメーター
client_list	利用可能なすべての再生クライアントを一覧表示します。	include_details: bool、active_only: bool
client_get_details	クライアントの詳細情報を取得します。	client_name、client_id
client_get_timelines	現在の再生状態／トラッカーを取得します。	client_name、client_id
client_start_playback	クライアントでメディア項目の再生を開始します。	media_title、client_name、rating_key、offset、library_name、use_external_player
client_control_playback	再生、一時停止、停止、シーク、スキップを実行します。	client_name、action、offset、client_id
client_navigate	リモートコントロールのナビゲーションコマンドを送信します。	client_name、command、client_id
client_set_streams	音声または字幕のトラックを変更します。	client_name、audio_stream_id、subtitle_stream_id、client_id

Response Formats

すべてのツールは、一貫した解析のために JSON 形式で情報を返します。

Success Example

{
  "status": "success",
  "data": {
    "title": "Inception",
    "year": 2010,
    "rating": 8.8
  }
}

Error Example

{
  "status": "error",
  "message": "Library 'Missing' not found."
}

Multiple Matches

操作で同じ名前の項目が複数見つかった場合、個別の識別子のリストが返されます。

[
  {
    "title": "The Office",
    "id": 123,
    "type": "show",
    "year": 2005
  },
  {
    "title": "The Office",
    "id": 456,
    "type": "show",
    "year": 1995
  }
]

Troubleshooting OAuth

• 401 Unauthorized：MCP_OAUTH_ISSUER が ID プロバイダーの発行者 URL（末尾のスラッシュを含む）と完全に一致していることを確認してください。MCP_OAUTH_AUDIENCE が設定されている場合、プロバイダーがトークンの aud クレームに設定するクライアント ID と一致している必要があります。
• Public URL：MCP_SERVER_URL はクライアントからアクセス可能である必要があります（例：plexmcp.example.com）。また、HTTPS を使用してください。
• Redirect URI mismatch（ログイン後にプロバイダーのエラーページが表示される）：クライアントのコールバックがプロバイダーのリダイレクトリストに含まれていません。手順 1 の表を参照してください。クライアントが要求する正確なコールバックを使用してください。Codex の場合は、例の <callback-id> を実際のコールバック ID に置き換えてください。変更されるのはループバックポートのみです。
• Client hangs after login / "Couldn't connect"：サーバーログで Token valid と Token validation failed のどちらが記録されているかを確認してください。/token の呼び出しが成功した直後に失敗する場合は、通常、MCP_OAUTH_AUDIENCE がトークンの aud と一致していません。確認のため一度設定を解除し、その後クライアント ID を設定してください。
• First request slow：トークン検証では、検出メタデータが再起動までキャッシュされ、JWKS は MCP_OAUTH_JWKS_CACHE_TTL 秒間（デフォルトは 3600 秒）キャッシュされます。プロバイダーの署名キーをローテーションした後は、サーバーを再起動するか、キャッシュの有効期限が切れるまでお待ちください。