Plex

---
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.

```bash
# 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

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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)

```bash
# 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)

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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](https://www.plexopedia.com/plex-media-server/api/)
- [Plex Web App](https://app.plex.tv/)

For detailed local reference, see:
- **[API Endpoints](./references/api-endpoints.md)** - Complete endpoint reference with parameters
- **[Quick Reference](./references/quick-reference.md)** - Common operations with copy-paste examples
- **[Troubleshooting](./references/troubleshooting.md)** - 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.