playbooks

home / skills / openclaw / skills / plex

plex skill

/skills/dbhurley/plex

This skill helps you control Plex Media Server to browse libraries, search media, and manage playback from one place.

npx playbooks add skill openclaw/skills --skill plex

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
2.1 KB
---
name: plex
description: Control Plex Media Server - browse libraries, search, play media, manage playback.
homepage: https://plex.tv
metadata: {"clawdis":{"emoji":"🎬","requires":{"bins":["curl"],"env":["PLEX_TOKEN","PLEX_SERVER"]},"primaryEnv":"PLEX_TOKEN"}}
---

# Plex Media Server

Control Plex Media Server using the Plex API.

## Setup

Set environment variables:
- `PLEX_SERVER`: Your Plex server URL (e.g., `http://192.168.1.100:32400`)
- `PLEX_TOKEN`: Your Plex auth token (find it at plex.tv/claim or in Plex app XML)

## Common Commands

### Get Server Info
```bash
curl -s "$PLEX_SERVER/?X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"
```

### Browse Libraries
```bash
curl -s "$PLEX_SERVER/library/sections?X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"
```

### List Library Contents
```bash
# Replace 1 with your library section key (from browse above)
curl -s "$PLEX_SERVER/library/sections/1/all?X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"
```

### Search
```bash
curl -s "$PLEX_SERVER/search?query=SEARCH_TERM&X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"
```

### Get Recently Added
```bash
curl -s "$PLEX_SERVER/library/recentlyAdded?X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"
```

### Get On Deck (Continue Watching)
```bash
curl -s "$PLEX_SERVER/library/onDeck?X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"
```

### Get Active Sessions (What's Playing Now)
```bash
curl -s "$PLEX_SERVER/status/sessions?X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"
```

### List Available Clients/Players
```bash
curl -s "$PLEX_SERVER/clients?X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"
```

## Library Section Types

- Movies (usually section 1)
- TV Shows (usually section 2)
- Music
- Photos

## Notes

- Add `-H "Accept: application/json"` for JSON output (default is XML)
- Library section keys (1, 2, 3...) vary by server setup — list sections first
- Media keys look like `/library/metadata/12345`
- Always confirm before starting playback on a device
- Get your token: plex.tv → Account → Authorized Devices → XML link

Overview

This skill lets you control a Plex Media Server remotely: browse libraries, search content, inspect what's playing, and initiate playback on clients. It uses the Plex HTTP API and requires your server URL and auth token. The skill is optimized for automating common media-management and playback tasks.

How this skill works

The skill calls Plex server endpoints with your PLEX_SERVER URL and PLEX_TOKEN to fetch server info, library sections, recent additions, search results, active sessions, and available clients. It returns JSON when requested and can trigger playback by targeting a client/player. Library section keys and media metadata are derived from the server responses, so the skill lists sections first to identify the correct keys.

When to use it

  • Automating playback on a specific client from scripts or chatbots
  • Building dashboards that show recently added or on-deck items
  • Searching across all libraries programmatically
  • Checking active sessions and who is currently watching
  • Listing available clients for remote control or casting

Best practices

  • Store PLEX_SERVER and PLEX_TOKEN as environment variables, not in code
  • List library sections first to discover section keys before requesting contents
  • Request JSON output with the Accept: application/json header for easier parsing
  • Confirm with users before starting playback on a shared device
  • Respect Plex account limits and avoid excessive polling of endpoints

Example use cases

  • A chatbot that accepts a movie name, searches Plex, and starts playback on the living room TV
  • A nightly job that lists recently added movies and posts new items to a media Slack channel
  • An admin tool that queries active sessions to detect transcoding bottlenecks
  • A home automation routine that pauses playback when a doorbell event occurs

FAQ

How do I get my PLEX_TOKEN?

Get your token from plex.tv (Account → Authorized Devices) or extract it from the Plex app XML; then set it as PLEX_TOKEN in your environment.

What format do responses use?

Endpoints default to XML; add the header Accept: application/json to receive JSON responses that are easier to parse.