Agent SkillsAgent Skills
eddmann

plex

@eddmann/plex
eddmann
3
0 forks
Updated 4/1/2026
View on GitHub

Query Plex Media Server for movies, TV shows, music, and playback history. Use when the user asks about their Plex library, "what movies do I have", "recently added", "continue watching", "watch history", "search my Plex", or wants to explore media in their Plex server.

Installation

$npx agent-skills-cli install @eddmann/plex
Claude Code
Cursor
Copilot
Codex
Antigravity

Details

Repositoryeddmann/jeeves
Pathskills/plex/SKILL.md
Branchmain
Scoped Name@eddmann/plex

Usage

After installing, this skill will be available to your AI coding assistant.

Verify installation:

npx agent-skills-cli list

Skill Instructions


name: plex description: Query Plex Media Server for movies, TV shows, music, and playback history. Use when the user asks about their Plex library, "what movies do I have", "recently added", "continue watching", "watch history", "search my Plex", or wants to explore media in their Plex server.

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:

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

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)

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:

export PLEX_SERVER_URL=$(grep PLEX_SERVER_URL .env | cut -d= -f2); uv run - <<'EOF'
# /// script
# requires-python = ">=3.11"
# dependencies = ["plexapi>=4.18"]
# ///
import json, os
from pathlib import Path
from plexapi.server import PlexServer

server_url = os.environ["PLEX_SERVER_URL"]
token = os.environ["PLEX_TOKEN"]

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)

print(f"SUCCESS: Connected to {plex.friendlyName}")
for section in plex.library.sections():
    print(f"  - {section.title} ({section.type})")
EOF

For the direct token approach, the user can find their token by opening any media item in the Plex web UI → Get Info → View XML → copy X-Plex-Token from the URL.

Query Template

export PLEX_SERVER_URL=$(grep PLEX_SERVER_URL .env | cut -d= -f2); uv run - <<'EOF'
# /// script
# requires-python = ">=3.11"
# dependencies = ["plexapi>=4.18"]
# ///
import json
from pathlib import Path
from plexapi.server import PlexServer

TOKEN_FILE = Path("plex-token.json")
if not TOKEN_FILE.exists():
    print("ERROR: Not authenticated — run Plex setup first")
    exit(1)

config = json.loads(TOKEN_FILE.read_text())
plex = PlexServer(config["server_url"], config["token"])

# === YOUR QUERY CODE HERE ===
for section in plex.library.sections():
    print(f"{section.title} ({section.type}): {section.totalSize} items")
EOF

API Reference

Server Methods

MethodReturnsDescription
plex.library.sections()list[LibrarySection]All library sections
plex.library.section(name)LibrarySectionGet section by title
plex.library.sectionByID(id)LibrarySectionGet section by ID
plex.library.onDeck()list[Media]On deck items
plex.library.recentlyAdded()list[Media]Recently added across all sections
plex.continueWatching()list[Media]Continue watching hub
plex.history(maxresults=N)list[Media]Watch history

Section Methods

MethodReturnsDescription
section.all()list[Media]All items in section
section.search(title, **filters)list[Media]Search with filters
section.recentlyAdded()list[Media]Recently added to section
section.onDeck()list[Media]On deck for section

Media Fields (Movie)

FieldTypeDescription
titlestrMovie title
yearintRelease year
durationintDuration in milliseconds
ratingfloatCritic rating
audienceRatingfloatAudience rating (Rotten Tomatoes)
contentRatingstrContent rating (PG-13, R, etc.)
summarystrPlot summary
genreslist[Genre]Genre tags (access .tag)
directorslist[Director]Directors (access .tag)
roleslist[Role]Cast members (access .tag)
studiostrProduction studio
addedAtdatetimeWhen added to library
lastViewedAtdatetimeLast watched (None if unwatched)
viewCountintTimes watched

Media Fields (Show)

FieldTypeDescription
titlestrShow title
yearintFirst aired year
childCountintNumber of seasons
leafCountintTotal episodes
viewedLeafCountintWatched episodes
durationintTypical episode duration (ms)

Media Fields (Episode)

FieldTypeDescription
titlestrEpisode title
grandparentTitlestrShow name
parentTitlestrSeason name
parentIndexintSeason number
indexintEpisode number
durationintDuration in milliseconds

Navigation (Shows)

MethodReturnsDescription
show.seasons()list[Season]All seasons
show.episodes()list[Episode]All episodes
show.episode(season=N, episode=M)EpisodeSpecific episode
season.episodes()list[Episode]Episodes in season

Examples

These show non-obvious patterns. For straightforward methods, use the API reference above.

TV Show Navigation (unintuitive field names)

shows = plex.library.section("TV Shows")
show = shows.get("Breaking Bad")
print(f"{show.title}: {show.leafCount} episodes")

for season in show.seasons():
    print(f"  {season.title}: {len(season.episodes())} episodes")

# Episode fields use grandparent/parent for show/season
ep = show.episode(season=1, episode=1)
print(f"{ep.grandparentTitle} S{ep.parentIndex}E{ep.index}: {ep.title}")

Search with Filters

movies = plex.library.section("Movies")

# Filter by genre + year
action = movies.search(genre="Action", year=2023)
for m in action:
    # Tags are objects — access .tag for the string
    genres = [g.tag for g in m.genres]
    print(f"{m.title} ({m.year}) - {', '.join(genres)}")

Quick Reference

# Unit conversions
duration_min = media.duration / 60000
duration_hrs = media.duration / 3600000

# Library section types
# "movie", "show", "artist" (music), "photo"

# Access tag names from lists
genres = [g.tag for g in movie.genres]
actors = [r.tag for r in movie.roles]
directors = [d.tag for d in movie.directors]

# Check if watched
is_watched = media.viewCount > 0
is_unwatched = media.lastViewedAt is None

Re-authentication

Plex tokens are long-lived but can be revoked. If queries fail with "Unauthorized", re-run the OAuth flow from the Setup section.

Debugging

If a method call fails or you're unsure what's available, introspect:

uv run -c "from plexapi.server import PlexServer; print([m for m in dir(PlexServer) if not m.startswith('_')])"

For full library docs: webfetch https://github.com/pkkid/python-plexapi

Troubleshooting

  • "Not authenticated": Run the OAuth flow from the Setup section
  • "Connection refused": Check PLEX_SERVER_URL, ensure server is running
  • "Unauthorized": Token revoked, re-run OAuth
  • Section not found: Use exact section title (case-sensitive), check plex.library.sections()
  • Empty results: Some methods return generators; convert with list() if needed
  • Rate limited (429): Plex API rate limits aggressively. Back off and retry. Avoid rapid repeated OAuth attempts.