# Plex

> Interact with a Plex Media Server to list libraries, search media, get item details, manage playlists and collections, export metadata, and trigger library rescans. Use when working with Plex servers.

- **Type:** Skill
- **Install:** `agentstack add skill-hevangel-media-agent-skills-plex`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hevangel](https://agentstack.voostack.com/s/hevangel)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [hevangel](https://github.com/hevangel)
- **Source:** https://github.com/hevangel/media-agent-skills/tree/main/skills/plex

## Install

```sh
agentstack add skill-hevangel-media-agent-skills-plex
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Plex Media Server API

## Configuration

All settings are loaded from the `.env` file in the workspace root.

```env
PLEX_URL=http://localhost:32400
PLEX_TOKEN=your_token
PLEX_USERNAME=your_username
PLEX_PASSWORD=your_password
```

Authentication methods (tried in order):
1. **Direct token** (recommended): `PLEX_URL` + `PLEX_TOKEN`
2. **MyPlex account** (fallback): `PLEX_USERNAME` + `PLEX_PASSWORD`

### Quick Token Setup

```bash
cd skills/plex/scripts
uv run python get_token.py
```

Supports MyPlex login, browser-based PIN auth, or manual token entry.

## Reference

- python-plexapi docs: https://python-plexapi.readthedocs.io/
- Code Snippets: `scripts/`

## Available Scripts

| Script | Purpose |
|--------|---------|
| `config.py` | Loads credentials from `.env` |
| `client.py` | Creates authenticated `PlexServer` instance |
| `get_token.py` | Interactive token helper |
| `list_libraries.py` | List all libraries |
| `get_library_items.py` | Get items from a library |
| `search_media.py` | Search by query, type, library |
| `get_item_details.py` | Full metadata for an item |
| `get_recently_added.py` | Recently added items |
| `refresh_library.py` | Trigger library refresh/scan |
| `dump_library_to_json.py` | Export library to JSON |
| `get_server_info.py` | Server info, active sessions |

## Key Patterns

### API Access

```python
from plexapi.server import PlexServer

plex = PlexServer(baseurl, token)
libraries = plex.library.sections()
section = plex.library.section('Movies')
results = plex.search('query')
item = plex.fetchItem(rating_key)
```

### Common Operations

- **Libraries**: `plex.library.sections()`, `plex.library.section('name')`
- **Search**: `plex.search('query')`, `section.search(query=..., libtype=...)`
- **Items**: `section.all()`, `plex.fetchItem(key)`, `section.recentlyAdded()`
- **Refresh**: `section.refresh()`, `section.update()`
- **TV Shows**: `show.seasons()`, `show.episodes()`, `show.episode(season=N, episode=M)`
- **Playlists**: `plex.playlists()`, `plex.createPlaylist(title, items=items)`
- **Collections**: `section.collections()`, `collection.items()`

### Item Metadata

- `title`, `year`, `summary`, `rating`, `contentRating`
- `[g.tag for g in item.genres]`, `[d.tag for d in item.directors]`
- `[g.id for g in item.guids]` (IMDB, TMDB, TVDB)
- `item.media[0].parts[0].file` (file path)

### Library/Item Types

`movie`, `show`, `season`, `episode`, `artist`, `album`, `track`, `photo`

## Usage Examples

```bash
cd skills/plex/scripts
uv run python list_libraries.py
uv run python search_media.py "Midway"
uv run python get_recently_added.py "Movies" 10
uv run python dump_library_to_json.py "Movies"
uv run python refresh_library.py "Movies"
```

## Notes

- Use `client.py` and `get_plex_client()` as the starting point.
- Temporary files go in `$WORKSPACE_PATH/temp/`.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hevangel](https://github.com/hevangel)
- **Source:** [hevangel/media-agent-skills](https://github.com/hevangel/media-agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-hevangel-media-agent-skills-plex
- Seller: https://agentstack.voostack.com/s/hevangel
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.