Plex Director

plex-director-mcp

Plex Director is a self-hosted assistant for a Plex + Servarr media stack. It connects to Plex, Radarr, Sonarr, Prowlarr, SABnzbd, qBittorrent, Tautulli and TMDb (and, optionally, your Linux hosts over SSH), and gives you two ways to work with them:

• An MCP server for Claude Desktop — ask Claude to find what you own, work out why a movie is missing, add movies, check your indexers and download queues, or run batch jobs.
• A web dashboard — a browser UI with a chat box ("Which of Harrison Ford's movies do I have in 4K?"), server status, host utilization, download queues, indexer health, and background jobs.

It is built for a home-run setup: run it on your LAN, next to the apps it talks to.

[!WARNING]

Plex Director holds the API keys for every service you connect and can change them, not just read them: it adds movies to Radarr and starts download searches, removes stalled torrents from qBittorrent, runs batch upgrade jobs, and triggers Servarr backups. Adding movies goes through a pick-then-confirm step and batch jobs are planned before they run, but purging stalled torrents and starting backups happen as soon as they are asked for, and the chat and Claude Desktop act with your keys. Set WEB_PASSWORD, keep the dashboard off the public internet, and see Security requirements.

Documentation

• Quick start, installing, upgrading and backups and verifying releases.
• The user guide: the dashboard pages, the Query chat and the MCP tools. The documentation index lists everything.
• Architecture: the components, who uses them, and how a question flows through them.
• Security requirements: what Plex Director does and doesn't protect against, and the assurance case behind it.
• Roadmap: where the project is going, and what it won't do.
• Accessibility: what the dashboard does today and the known gaps.
• External interfaces (the dashboard's HTTP API is described in docs/api/openapi.json) and dependencies and vulnerability management.
• Support: which versions get fixes, and for how long. Changelog.
• Contributing, Code of Conduct, Governance and reporting a vulnerability.

Contents

• Documentation
• What it can do
• Quick start
• Docker
• Supported architectures
• Image tags
• Application setup
• Usage — Docker Compose · Docker CLI · Claude Desktop via Docker
• Parameters
• Environment variable reference
• Read-only and non-root operation
• Updating
• Building locally
• Run without Docker (Claude Desktop)
• Web dashboard
• MCP tools
• Security
• Development
• CI/CD
• License

What it can do

• Find what you own. Search your Plex library, movies and TV shows, by genre, actor, title, year and library (for example just the 4K libraries) across every library at once. A title held in both HD and 4K is one result with both libraries shown, and shows come with their season and episode counts and how much you have watched. You can leave a library such as Sports out of searches unless you name it.
• Do I have every episode? Ask about a show and Sonarr's episode list says how many aired episodes are downloaded and exactly which are missing, or ask which of your shows have gaps, ranked, including near-complete ones. Unaired episodes and specials are never counted as missing. For a missing episode it can also say why, from Sonarr's history and download queue.
• What's on, and when does it return? See which episodes air in the next few days, with premieres and finales flagged, or ask when a particular show comes back (or that no date has been announced yet).
• What should I watch next? Ask for what is on deck: the next episode of each show you are following and the movies you did not finish, with how far through each one is.
• What have I watched, and what have I let go stale? Ask for unwatched shows, ones you started but never finished, movies you have not watched in years, or the newest additions, alone or combined with genre, library and the rest. Titles Plex says were watched but holds no date for are set aside and counted, not guessed at.
• Owned versus missing. Look up an actor's TMDb filmography, movies and TV shows, and see which of those titles are in Plex and which are not, optionally narrowed to movies or shows, by year range, or by "in 4K". Talk-show and "Self" appearances are left out, and a title appears once even when the actor played several roles in it.
• Diagnose and add movies. Trace a movie through Radarr metadata, history and the download queues to see why it is missing, or search TMDb, pick from a grid, and add the choices to Radarr with a download search.
• Watch your downloads and indexers. See SABnzbd and qBittorrent queues, clean up stalled torrents, and check every Prowlarr indexer's health (including ones that are backing off).
• Run batch jobs safely. Plan a movie-upgrade batch and let a rate-limited runner search one movie a minute, with pause, resume, cancel, and automatic pausing if Radarr stops responding.
• Keep an eye on your hosts. CPU, memory, disk, uptime and Docker container health for your Linux hosts over SSH, plus Radarr, Sonarr and Prowlarr built-in backups on demand. Each host's SSH key is remembered the first time it connects, and a changed key is refused until you approve it.
• Understand usage. Live Plex streams and watch statistics through Tautulli.
• Stay informed. Optional Discord notifications when a batch job finishes or is paused.

Quick start

From v1.2.0, Plex Director is listed in the official MCP registry as io.github.HoneyBearTech/plex-director-mcp, so MCP clients that browse the registry can install it directly (server.json lists its settings). Otherwise, the fastest way to try it is Docker Compose:

---

services: plex-director: image: honeybeartech/plex-director-mcp:latest container_name: plex-director environment:

• WEB_PASSWORD=choose-a-password volumes:
• ./data:/app/data ports:
• 3000:3000 restart: unless-stopped

docker compose up -d

Then open http://localhost:3000, sign in, and fill in your services on the Settings page (Radarr, Sonarr, Prowlarr, SABnzbd, qBittorrent, Tautulli, Plex, TMDb). The full guide, with every option, is in Docker below. To use it from Claude Desktop instead, see Claude Desktop via Docker.

Docker

Images are published to both registries, and both are signed (see CI/CD):

Everything below works with either; the examples use Docker Hub.

Supported architectures

Multi-arch manifests are published, so pulling the image gets the right one for your machine automatically.

Image tags

Release notes for the numbered versions are on the Releases page.

Application setup

1. Start the container with one of the usage examples and open the web UI at http:// :3000.
2. Set a password. Add WEB_PASSWORD to the container's environment. Without it, the dashboard is open to anyone who can reach the port, including the Settings page, and shows a warning banner. See Security.
3. Add your services. Open Settings and fill in each tab. Every field can also be given as an environment variable (see the reference), which is handy for automated setups. You only need the services you actually use.
4. Give the chat box a brain. The Query page uses Claude to answer questions, so it needs ANTHROPIC_API_KEY in the container's environment. This is a pay-per-use Anthropic API key, separate from a Claude subscription. The rest of the dashboard works without it.
5. Keep the data volume. Your settings, job history and the secret that keeps you signed in live in a SQLite database at /app/data. Mount a volume there or you will lose them each time the container is recreated.

Where to find each credential:

Networking: inside the container, localhost is the container itself, not your server. Use the LAN address of ea