plex

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 Media Server
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:

1. Go to plex.tv → Account → Authorized Devices
2. Click on any device, then "View XML"
3. Find X-Plex-Token in the URL
4. 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

# Using helper script
bash skills/plex/scripts/plex-api info

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

Browse Libraries

List all library sections:

# Using helper script
bash skills/plex/scripts/plex-api libraries

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

List Library Contents

# Using helper script (replace 1 with your section key)
bash skills/plex/scripts/plex-api library 1
bash skills/plex/scripts/plex-api 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"

Search Media

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

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

Recently Added

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

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

On Deck (Continue Watching)

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

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

Active Sessions (What's Playing)

# Using helper script
bash skills/plex/scripts/plex-api sessions

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

List Clients/Players

# Using helper script
bash skills/plex/scripts/plex-api clients

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

Additional Commands

# Server identity
bash skills/plex/scripts/plex-api identity

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

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

# List playlists
bash skills/plex/scripts/plex-api playlists

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

# View all commands
bash skills/plex/scripts/plex-api --help

Workflow

When the user asks about Plex:

1. "What's on Plex?" → Browse libraries and show section overview
2. "Search for Inception" → Run search with query
3. "What was recently added?" → Run recentlyAdded
4. "Who's watching right now?" → Run sessions
5. "What am I watching?" → Run onDeck
6. "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:

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

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

Reference

• Plex Media Server API
• Plex Web App

For detailed local reference, see:

• API Endpoints - Complete endpoint reference with parameters
• Quick Reference - Common operations with copy-paste examples
• Troubleshooting - Authentication, connection, and error solutions

---

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.