plex

Files (1)

• SKILL.md

SKILL.md (first lines)

# Plex Skill

Query Plex Media Server by writing UV inline Python scripts using plexapi.

## Setup

### Credentials

Requires `PLEX_SERVER_URL` in `workspace/.env`.

If not set, ask the user for their Plex server URL (e.g. `http://192.168.1.100:32400`), then append to `.env`:

```bash
echo 'PLEX_SERVER_URL=http://their-server:32400' >> .env
```

### Authentication

Plex uses OAuth with a PIN-based flow. This MUST be done in two separate steps because you need to show the user the link and wait for them to click it before polling.

**Step 1: Generate auth URL and save state**

```bash
set -a; source .env 2>/dev/null; set +a; uv run - <<'EOF'
# /// script
# requires-python = ">=3.11"
# dependencies = ["plexapi>=4.18"]
# ///
import json
from pathlib import Path
from plexapi.myplex import MyPlexPinLogin

pinlogin = MyPlexPinLogin(oauth=True)
code = pinlogin._getCode()
pin_id = pinlogin._id
client_id = pinlogin._headers()['X-Plex-Client-Identifier']

# Save state for step 2
Path("plex-oauth-state.json").write_text(json.dumps({
    "pin_id": pin_id,
    "code": code,
    "client_id": client_id,
}))

print(f"URL: {pinlogin.oauthUrl()}")
EOF
```

Send the URL to the user as a clickable markdown link. Tell them to sign in and let you know when done.
The PIN is valid for ~15 minutes so there's no rush.

**IMPORTANT:** Do NOT call `pinlogin.run()` or `pinlogin.waitForLogin()` — these start a blocking polling thread that will timeout before the user can click the link. Instead, manually call `_getCode()` and save the state.

**Step 2: Poll for token** (run ONLY after user confirms they've signed in)

```bash
export PLEX_SERVER_URL=$(grep PLEX_SERVER_URL .env | cut -d= -f2); uv run - <<'EOF'
# /// script
# requires-python = ">=3.11"
# dependencies = ["plexapi>=4.18", "requests"]
# ///
import json, os, requests, time, xml.etree.ElementTree as ET
from pathlib import Path
from plexapi.server import PlexServer
from plexapi.myplex import MyPlexAccount

state = json.loads(Path("plex-oauth-state.json").read_text())

headers = {
    "Accept": "application/xml",
    "X-Plex-Client-Identifier": state["client_id"],
    "X-Plex-Product": "PlexAPI",
}

# Poll with backoff to avoid rate limiting (429)
for i in range(15):
    resp = requests.get(
        f"https://plex.tv/api/v2/pins/{state['pin_id']}",
        headers=headers, timeout=10
    )
    if resp.status_code == 429:
        time.sleep(5)
        continue
    if resp.status_code == 200:
        root = ET.fromstring(resp.text)
        token = root.attrib.get('authToken', '')
        if token:
            server_url = os.environ["PLEX_SERVER_URL"]
            plex = PlexServer(server_url, token)
            Path("plex-token.json").write_text(json.dumps({
                "token": token,
                "server_url": server_url
            }, indent=2))
            Path("plex-token.json").chmod(0o600)
            account = MyPlexAccount(token=token)
            print(f"SUCCESS: Connected as {account.username}")
            print(f"Server: {plex.friendlyName}")
            for section in plex.library.sections():
                print(f"  - {section.title} ({section.type})")
            exit(0)
    time.sleep(3)

print("ERROR: No token received. Ask user to try signing in again.")
exit(1)
EOF
```

**Key details about the OAuth flow:**

- `MyPlexPinLogin.run()` generates a NEW pin and starts a blocking thread — don't use it for two-step auth
- `MyPlexPinLogin.pin` raises `BadRequest` when `oauth=True` — don't access it
- Use `_getCode()` to generate the PIN without starting the polling thread
- Save `_id` (pin ID), `_code`, and the client identifier to a file between steps
- In step 2, poll the Plex API directly with `requests` using the saved pin ID
- Plex rate limits aggressively — poll every 3s, back off on 429s

**Alternative: direct token auth.** If the user already has a Plex token, skip OAuth and store it directly:

```bash

From eddmann/jeeves, MIT.

More from eddmann/jeeves