plex

Plex Media Server スキル

⚠️ スキルの呼び出しは必須です ⚠️

ユーザーが以下のトリガーのいずれかに言及した場合、このスキルを必ず呼び出してください（任意ではありません）：

• 「Plex library」、「search Plex」、「what's on Plex」
• 「Plex sessions」、「who's watching」、「active streams」
• 「browse Plex」、「check Plex」、「Plex status」
• Plex Media Server またはメディアのクエリに関するあらゆる言及

トリガーが発生したときにこのスキルを呼び出さないと、運用要件に違反します。

Plex API を使用して Plex Media Server を操作および照会します。ライブラリの閲覧、メディアの検索、アクティブなセッションの監視ができます。

目的

このスキルでは、Plex Media Server に読み取り専用でアクセスできます。

• ライブラリセクション（Movies、TV、Music、Photos）を閲覧する
• 特定のメディアを検索する
• 最近追加されたコンテンツを表示する
• 現在再生中のコンテンツ（アクティブなセッション）を確認する
• 「On Deck」（視聴を続ける）を表示する
• 利用可能なクライアント／プレーヤーを一覧表示する

すべての操作はGET のみで、安全に監視や閲覧を行えます。

セットアップ

Plex サーバーの認証情報を ~/.claude-homelab/.env に追加します。

# Plex Media Server
PLEX_URL="http://192.168.1.100:32400"
PLEX_TOKEN="<your_plex_token>"

• PLEX_URL：ポートを含む Plex サーバーの URL（デフォルト：32400）
• PLEX_TOKEN：Plex 認証トークン

Plex トークンの取得方法：

1. plex.tv → Account → Authorized Devices に移動します
2. 任意のデバイスをクリックして、「View XML」をクリックします
3. URL 内の X-Plex-Token を探します
4. または、Plex Web で任意のメディアを開き、「Get Info」→「View XML」をクリックして、URL 内のトークンを探します

コマンド

すべてのコマンドは JSON を出力します。整形やフィルタリングには jq を使用してください。

plex-api.sh ヘルパースクリプトを使うと、API に簡単にアクセスできます。場所：skills/plex/scripts/plex-api.sh

サーバー情報

# Using helper script
./skills/plex/scripts/plex-api.sh info

# Or raw curl
curl -s "$PLEX_URL/?X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"

ライブラリを閲覧する

すべてのライブラリセクションを一覧表示します。

# Using helper script
./skills/plex/scripts/plex-api.sh libraries

# Or raw curl
curl -s "$PLEX_URL/library/sections?X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"

ライブラリのコンテンツを一覧表示する

# Using helper script (replace 1 with your section key)
./skills/plex/scripts/plex-api.sh library 1
./skills/plex/scripts/plex-api.sh library 1 --limit 50 --offset 100

# Or raw curl
curl -s "$PLEX_URL/library/sections/1/all?X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"

メディアを検索する

# Using helper script
./skills/plex/scripts/plex-api.sh search "Inception"
./skills/plex/scripts/plex-api.sh search "Avengers" --limit 10

# Or raw curl
curl -s "$PLEX_URL/search?query=SEARCH_TERM&X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"

最近追加されたコンテンツ

# Using helper script (default: 20 items)
./skills/plex/scripts/plex-api.sh recent
./skills/plex/scripts/plex-api.sh recent --limit 10

# Or raw curl
curl -s "$PLEX_URL/library/recentlyAdded?X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"

On Deck（視聴を続ける）

# Using helper script (default: 10 items)
./skills/plex/scripts/plex-api.sh ondeck
./skills/plex/scripts/plex-api.sh ondeck --limit 5

# Or raw curl
curl -s "$PLEX_URL/library/onDeck?X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"

アクティブなセッション（再生中のコンテンツ）

# Using helper script
./skills/plex/scripts/plex-api.sh sessions

# Or raw curl
curl -s "$PLEX_URL/status/sessions?X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"

クライアント／プレーヤーを一覧表示する

# Using helper script
./skills/plex/scripts/plex-api.sh clients

# Or raw curl
curl -s "$PLEX_URL/clients?X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"

その他のコマンド

# Server identity
./skills/plex/scripts/plex-api.sh identity

# Get metadata for specific item (by rating key)
./skills/plex/scripts/plex-api.sh metadata 12345

# Get children of item (e.g., seasons of a TV show)
./skills/plex/scripts/plex-api.sh children 12345

# List playlists
./skills/plex/scripts/plex-api.sh playlists

# Refresh library section (scan for new media)
./skills/plex/scripts/plex-api.sh refresh 1

# View all commands
./skills/plex/scripts/plex-api.sh --help

ワークフロー

ユーザーから Plex について尋ねられた場合：

1. 「Plex に何がありますか？」 → ライブラリを閲覧し、セクションの概要を表示します
2. 「Inception を検索して」 → クエリを指定して検索を実行します
3. 「最近追加されたものは？」 → recentlyAdded を実行します
4. 「今、誰が視聴していますか？」 → sessions を実行します
5. 「今、何を見ていますか？」 → onDeck を実行します
6. 「映画を一覧表示して」 → ライブラリセクションを一覧表示し、次に Movies セクションのコンテンツを一覧表示します

ライブラリセクションの種類

一般的なセクションの種類（キーはサーバーによって異なります）：

• Movies — 通常はセクション 1
• TV Shows — 通常はセクション 2
• Music — 音楽ライブラリ
• Photos — 写真ライブラリ

必ず最初にセクションを一覧表示し、サーバーで正しいセクションキーを取得してください。

出力形式

• JSON 出力には -H "Accept: application/json" を追加します
• ヘッダーを指定しない場合、デフォルトの出力は XML です
• メディアキーは /library/metadata/12345 のような形式です
• JSON レスポンスのフィルタリングや整形には jq を使用します

注意事項

• Plex サーバーへのネットワークアクセスが必要です
• すべての呼び出しは読み取り専用の GET リクエストです
• ライブラリセクションキー（1、2、3 など）はサーバーの設定によって異なるため、最初にセクションを一覧表示してください
• 再生制御は可能ですが、安全上の理由から実装されていません
• リモートデバイスで再生を開始する前に、必ず確認してください
• トークンはアカウントに紐付いています。安全に管理してください

複数のサーバー

複数の Plex サーバーを照会するには：

# Server 1
PLEX_URL="http://server1:32400" PLEX_TOKEN="token1" curl ...

# Server 2
PLEX_URL="http://server2:32400" PLEX_TOKEN="token2" curl ...

参考資料

• Plex Media Server API
• Plex Web App

ローカルの詳細な参考資料については、以下を参照してください。

• API エンドポイント - パラメーターを含む完全なエンドポイントリファレンス
• クイックリファレンス - コピーして貼り付けられる例を含む一般的な操作
• トラブルシューティング - 認証、接続、エラーの解決方法

---

🔧 エージェントのツール使用要件

重要： zsh-tool 経由でこのスキルのスクリプトを呼び出す場合は、必ず pty: true を使用してください。

PTY モードを使用しないと、コマンドは正常に実行されても、出力が表示されません。

正しい呼び出しパターン：

<invoke name="mcp__plugin_zsh-tool_zsh-tool__zsh">
<parameter name="command">./skills/SKILL_NAME/scripts/SCRIPT.sh [args]</parameter>
<parameter name="pty">true</parameter>
</invoke>