| name | plex |
| description | Control Plex Media Server - browse libraries, search media, check what's playing, view recently added. Use when the user asks to "check Plex", "search Plex", "what's on Plex", "recently added", "what did I add to Plex recently", "continue watching", "on deck", "what was I watching", "who's watching", "Plex sessions", "Plex library", "browse movies", "browse TV shows", "is Plex working", "my Plex collection", "refresh library", "scan Plex for new media", "Plex playlists", or mentions Plex media server. |
Plex Media Server Skill
Control and query Plex Media Server using the Plex API. Browse libraries, search media, and monitor active sessions.
Purpose
This skill provides primarily read access to your Plex Media Server:
- Browse library sections (Movies, TV, Music, Photos)
- Search for specific media
- View recently added content
- Check what's currently playing (active sessions)
- View "On Deck" (continue watching)
- List available clients/players
- Refresh library sections to scan for new media (triggers a scan — not read-only)
Setup
Add credentials to ~/.config/overseerr-mcp/.env (or ~/.config/overseerr-mcp/.env). Run the config-media-stack skill to configure automatically.
PLEX_URL="http://192.168.1.100:32400"
PLEX_TOKEN="<your_plex_token>"
PLEX_URL: Your Plex server URL with port (default: 32400)
PLEX_TOKEN: Your Plex authentication token
Getting your Plex token:
- Go to plex.tv → Account → Authorized Devices
- Click on any device, then "View XML"
- Find
X-Plex-Token in the URL
- Or: Open any media in Plex Web, click "Get Info" → "View XML" and find token in URL
Commands
All commands output JSON. Use jq for formatting or filtering.
The plex-api helper script simplifies API access. Located at: skills/plex/scripts/plex-api
Server Info
bash skills/plex/scripts/plex-api info
curl -s "$PLEX_URL/?X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"
Browse Libraries
List all library sections:
bash skills/plex/scripts/plex-api libraries
curl -s "$PLEX_URL/library/sections?X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"
List Library Contents
bash skills/plex/scripts/plex-api library 1
bash skills/plex/scripts/plex-api library 1 --limit 50 --offset 100
curl -s "$PLEX_URL/library/sections/1/all?X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"
Search Media
bash skills/plex/scripts/plex-api search "Inception"
bash skills/plex/scripts/plex-api search "Avengers" --limit 10
curl -s "$PLEX_URL/search?query=SEARCH_TERM&X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"
Recently Added
bash skills/plex/scripts/plex-api recent
bash skills/plex/scripts/plex-api recent --limit 10
curl -s "$PLEX_URL/library/recentlyAdded?X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"
On Deck (Continue Watching)
bash skills/plex/scripts/plex-api ondeck
bash skills/plex/scripts/plex-api ondeck --limit 5
curl -s "$PLEX_URL/library/onDeck?X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"
Active Sessions (What's Playing)
bash skills/plex/scripts/plex-api sessions
curl -s "$PLEX_URL/status/sessions?X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"
List Clients/Players
bash skills/plex/scripts/plex-api clients
curl -s "$PLEX_URL/clients?X-Plex-Token=$PLEX_TOKEN" -H "Accept: application/json"
Additional Commands
bash skills/plex/scripts/plex-api identity
bash skills/plex/scripts/plex-api metadata 12345
bash skills/plex/scripts/plex-api children 12345
bash skills/plex/scripts/plex-api playlists
bash skills/plex/scripts/plex-api refresh 1
bash skills/plex/scripts/plex-api --help
Workflow
When the user asks about Plex:
- "What's on Plex?" → Browse libraries and show section overview
- "Search for Inception" → Run search with query
- "What was recently added?" → Run recentlyAdded
- "Who's watching right now?" → Run sessions
- "What am I watching?" → Run onDeck
- "List my movies" → List library sections, then contents of Movies section
Library Section Types
Common section types (keys vary by server):
- Movies — Usually section 1
- TV Shows — Usually section 2
- Music — Music library
- Photos — Photo library
Always list sections first to get the correct section keys for your server.
Output Format
- Add
-H "Accept: application/json" for JSON output
- Default output is XML if header not specified
- Media keys look like
/library/metadata/12345
- Use
jq to filter and format JSON responses
Notes
- Requires network access to your Plex server
- Most operations are read-only;
refresh triggers a library scan (write side-effect) — safe but not instantaneous
- Library section keys (1, 2, 3...) vary by server setup — list sections first
- Additional admin commands available:
accounts (list Plex accounts), prefs (server preferences)
- Playback control is possible but not implemented (safety)
- Always confirm before triggering playback on remote devices
- Token is scoped to your account — keep it secure
Multiple Servers
To query multiple Plex servers:
PLEX_URL="http://server1:32400" PLEX_TOKEN="token1" curl ...
PLEX_URL="http://server2:32400" PLEX_TOKEN="token2" curl ...
Reference
For detailed local reference, see:
Agent Tool Usage Requirements
When running script commands via the zsh tool, always pass pty: true — without it, command output will be suppressed even though the command executes successfully.