plex

Plex Media Server 技能

⚠️ 必须调用此技能 ⚠️

用户提及以下任意触发词时，必须调用此技能（不可跳过）：

• “Plex 媒体库”“搜索 Plex”“Plex 上有什么”
• “Plex 会话”“谁在观看”“活跃串流”
• “浏览 Plex”“检查 Plex”“Plex 状态”
• 任何提及 Plex Media Server 或查询媒体的内容

触发时未调用此技能将违反操作要求。

使用 Plex API 控制和查询 Plex Media Server。浏览媒体库、搜索媒体并监控活跃会话。

用途

此技能提供对 Plex Media Server 的只读访问权限：

• 浏览媒体库分区（电影、电视、音乐、照片）
• 搜索特定媒体
• 查看最近添加的内容
• 检查当前正在播放的内容（活跃会话）
• 查看“接下来播放”（继续观看）
• 列出可用客户端／播放器

所有操作都仅使用 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 → 账户 → 已授权设备
2. 点击任意设备，然后点击“查看 XML”
3. 在 URL 中找到 X-Plex-Token
4. 或者：在 Plex Web 中打开任意媒体，点击“获取信息”→“查看 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"

接下来播放（继续观看）

# 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. “搜索《盗梦空间》” → 使用查询词运行搜索
3. “最近添加了什么？” → 运行 recentlyAdded
4. “现在谁在观看？” → 运行 sessions
5. “我在看什么？” → 运行 onDeck
6. “列出我的电影” → 列出媒体库分区，然后列出“电影”分区的内容

媒体库分区类型

常见分区类型（键值因服务而异）：

• 电影 — 通常为分区 1
• 电视节目 — 通常为分区 2
• 音乐 — 音乐媒体库
• 照片 — 照片媒体库

请先列出分区，以获取适用于你的服务的正确分区键值。

输出格式

• 添加 -H "Accept: application/json" 以获取 JSON 输出
• 未指定请求头时，默认输出 XML
• 媒体键的形式如 /library/metadata/12345
• 使用 jq 筛选和格式化 JSON 响应

注意事项

• 需要能够通过网络访问 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 端点 - 包含参数的完整端点参考
• 快速参考 - 常见操作及可复制粘贴的示例
• 故障排除 - 身份验证、连接和错误解决方案

---

🔧 Agent 工具使用要求

重要： 通过 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>