Plex Director

plex-director-mcp

[CI/CD] [CodeQL] [OpenSSF Scorecard] [OpenSSF Best Practices] [OpenSSF Baseline] [Docker Pulls] [Docker Version] [Image Size] [Node] [License]

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://<host>: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 each service (for example http://192.168.1.10:7878), or, if the other apps are in the same Compose project or Docker network, their service names (http://radarr:7878).

Usage

Here are some example snippets to help you get started creating a container. Docker Compose is recommended.

Docker Compose (recommended)

---services:  plex-director:    image: honeybeartech/plex-director-mcp:latest    container_name: plex-director    environment:      - WEB_PASSWORD=choose-a-password      - ANTHROPIC_API_KEY=sk-ant-your-key #optional, needed for the Query chat      - RADARR_URL=http://192.168.1.10:7878 #optional, or set on the Settings page      - RADARR_API_KEY=your_radarr_api_key #optional      - PLEX_URL=http://192.168.1.10:32400 #optional      - PLEX_TOKEN=your_plex_token #optional      - TMDB_API_KEY=your_tmdb_read_access_token #optional      - DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/... #optional    volumes:      - /path/to/plex-director/data:/app/data      - /path/to/ssh/id_ed25519:/ssh/id_ed25519:ro #optional, for host monitoring over SSH    ports:      - 3000:3000    restart: unless-stopped

The image has a built-in health check (docker ps shows healthy once it is up), so you don't need to add one.

To keep your credentials out of the compose file, put them in a .env-style file next to it and reference it instead of listing them:

    env_file:      - plex-director.env

Then start it:

docker compose up -d

Docker CLI

docker run -d \  --name=plex-director \  -e WEB_PASSWORD=choose-a-password \  -e ANTHROPIC_API_KEY=sk-ant-your-key \  -p 3000:3000 \  -v /path/to/plex-director/data:/app/data \  --restart unless-stopped \  honeybeartech/plex-director-mcp:latest

Add any other variables from the reference with more -e flags, or put them in a file and pass --env-file plex-director.env. For SSH host monitoring, also add -v /path/to/ssh/id_ed25519:/ssh/id_ed25519:ro.

--env-file is not the same as a .env file for Node. Docker reads values literally: don't put quotes around values, and don't put a comment after a value on the same line (KEY=abc # my key becomes the value abc # my key). Put comments on their own line.

Claude Desktop via Docker

The same image is also the MCP server, which speaks over stdio. Tell Claude Desktop to run it with docker run -i in its config (Settings → Developer → Edit Config, claude_desktop_config.json):

{  "mcpServers": {    "plex-director": {      "command": "docker",      "args": [        "run", "-i", "--rm",        "--env-file", "/absolute/path/to/plex-director.env",        "-v", "plex-director-data:/app/data",        "honeybeartech/plex-director-mcp:latest"      ]    }  }}

Restart Claude Desktop and the plex-director server appears as a tool provider (26 tools, listed below). Notes:

• -i is required, since MCP talks over stdin/stdout. Don't add -t.
• No -p is needed. The web dashboard also starts inside this container, but you only need to publish its port if you want to open it from this container instead of from the Compose one.
• If you also run the long-lived container above, give both the same data volume (or bind mount) so they share settings and job history.
• The container keeps running if Claude closes its stdin; quitting Claude Desktop stops it, or use docker stop.

Parameters

Container images are configured using parameters passed at runtime. These parameters are separated by a colon and indicate <external>:<internal> respectively. For example, -p 8080:3000 would expose port 3000 from inside the container to be accessible from the host's IP on port 8080 outside the container.

Environment variable reference

Nothing is required to start the container: it boots with no configuration and lets you fill things in on the Settings page.

Service connections. On first start these are copied into the database, and from then on the value saved in the database wins (that is what the Settings page edits). If you change one of these variables later and nothing happens, that is why; change it on the Settings page, or delete the database.

Container settings. These are read from the environment every time and are never stored in the database or shown on the Settings page.

Read-only and non-root operation

The container runs as a non-root user, UID and GID 65532 (distroless's nonroot), from 1.3.0 on; earlier versions ran as root. The image has no shell or package manager, and the data directory is the only place it writes, so it also runs with a read-only filesystem and no capabilities:

services:  plex-director:    image: honeybeartech/plex-director-mcp:latest    read_only: true    cap_drop:      - ALL    security_opt:      - no-new-privileges:true    volumes:      - /path/to/plex-director/data:/app/data    ports:      - 3000:3000

Or with the CLI: --read-only --cap-drop ALL --security-opt no-new-privileges:true.

A named volume works as it is: Docker gives a new volume the image's ownership of /app/data. A host folder must belong to UID 65532 first: sudo chown -R 65532:65532 /path/to/plex-director/data. To run as another user instead, for example one that already owns the folder, add user: "1000:1000" (or --user 1000:1000). If the data directory isn't writable, the container stops at startup and prints the chown to run. Upgrading from 1.2.x or earlier, whose data belongs to root: see upgrading. If you use SSH host monitoring, the mounted key must also be readable by the container's user.

Updating

Your settings and job history live in the data volume, so updating just replaces the container.

Docker Compose

docker compose pull plex-directordocker compose up -ddocker image prune

Docker CLI

docker pull honeybeartech/plex-director-mcp:latestdocker stop plex-directordocker rm plex-director# ...then run the same `docker run` command as beforedocker image prune

Verify a download. Every published image is signed with cosign using GitHub's OIDC identity (no keys to manage):

cosign verify \  --certificate-identity-regexp "https://github.com/HoneyBearTech/plex-director-mcp/.*" \  --certificate-oidc-issuer https://token.actions.githubusercontent.com \  honeybeartech/plex-director-mcp:latest

Building locally

git clone https://github.com/HoneyBearTech/plex-director-mcp.gitcd plex-director-mcpdocker build -t plex-director-mcp .

.dockerignore keeps .env, the local database and other secrets out of the build context. Never bake secrets into an image; pass them at run time.

Run without Docker (Claude Desktop)

Requires Node.js 24.

git clone https://github.com/HoneyBearTech/plex-director-mcp.gitcd plex-director-mcpnpm install# Build the dashboard; without this the web UI has nothing to serve.cd web && npm install && npm run build && cd ..

Create a .env file in the repo root with the services you use (all optional; you can also enter service details later on the Settings page):

RADARR_URL=http://radarr:7878RADARR_API_KEY=your_radarr_api_keyRADARR_DEFAULT_QUALITY_PROFILE=Your Profile NameSONARR_URL=http://sonarr:8989SONARR_API_KEY=your_sonarr_api_keyPROWLARR_URL=http://prowlarr:9696PROWLARR_API_KEY=your_prowlarr_api_keySABNZBD_URL=http://sabnzbd:8080SABNZBD_API_KEY=your_sabnzbd_api_keyQBITTORRENT_URL=http://qbittorrent:8080QBITTORRENT_USER=your_qbittorrent_userQBITTORRENT_PASS=your_qbittorrent_passwordTAUTULLI_URL=http://tautulli:8181TAUTULLI_API_KEY=your_tautulli_api_keyPLEX_URL=http://plex:32400PLEX_TOKEN=your_plex_tokenTMDB_API_KEY=your_tmdb_read_access_tokenANTHROPIC_API_KEY=your_anthropic_api_keyUBUNTU_HOSTS=192.168.1.10,192.168.1.11SSH_USER=your_ssh_usernameSSH_KEY_PATH=/path/to/id_ed25519SSH_KEY_PASSPHRASE=only_if_the_key_has_oneDISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...WEB_PORT=3000WEB_PASSWORD=choose-a-password

See the reference for what each one does. Two things that commonly go wrong:

• Comments go on their own line, never after a value (KEY=abc # note makes the note part of the value in some tools).
• A path with a space needs quotes around the whole value: SSH_KEY_PATH="/Users/me/.ssh/my key", not /Users/me/.ssh/'my key'.

Add the server to Claude Desktop (Settings → Developer → Edit Config):

{  "mcpServers": {    "plex-director": {      "command": "npx",      "args": ["-y", "tsx", "/absolute/path/to/plex-director-mcp/src/index.ts"],      "env": { "NODE_ENV": "production" }    }  }}

Replace the path with the real one and restart Claude Desktop. The server starts the web dashboard on WEB_PORT in the same process.

Web dashboard

The dashboard runs on WEB_PORT (default 3000) in the same process as the MCP server.

Set WEB_PASSWORD to require a login: a sign-in page, then a signed 7-day session cookie (marked Secure automatically when served over HTTPS). Failed logins are rate-limited. Logging out only clears your browser's copy, so to revoke every session, change the password.

The health check is GET /healthz, which returns {"ok":true} and needs no login. The Docker image runs it for you every 30 seconds using Node itself (the image has no curl), on whatever WEB_PORT is set to.

MCP tools

Twenty-six tools are available to Claude Desktop. The twelve marked ★ are also what the dashboard's Query chat uses.

The server also sends MCP clients short usage instructions: which tool answers which kind of question, and to confirm before anything that changes your services. The same guidance is in an Agent Skill for agents that load skills (such as Claude Code), and in the Query chat's prompt. It is written once in src/guidance.ts.

Your library

Downloads and indexers

Background jobs

Infrastructure and analytics

How batch jobs work. plan_media_upgrade creates a job in the PENDING state; nothing runs until you RESUME it. A started job is then advanced by the job runner, one Radarr search per interval (default 60 seconds), so a large batch cannot flood your indexers. A paused, cancelled or pending job is never touched, and a job that fails three times in a row (for example because Radarr is down) is paused and reported to Discord.

Security

• Run it on a trusted network. It is designed for a home LAN and is not designed or tested to be exposed to the public internet. If you do reach it from outside, put it behind HTTPS and a reverse proxy you trust. See SECURITY.md to report a vulnerability.
• Set WEB_PASSWORD. Without it, anyone who can reach the port can use the dashboard and change its settings.
• Secrets stay on the server. The Settings page never returns a saved key or token, and Plex artwork is fetched through a server-side proxy so the Plex token never reaches your browser.
• SSH host monitoring uses key authentication, and remembers each host's key on first use. The first time a host connects, its key fingerprint is saved; from then on a different key is refused before any command is sent, and the Node Utilization page shows the host as offline with a Trust new key button for when you have legitimately rebuilt it (that button needs WEB_PASSWORD; without one, ask Claude Desktop to use trust_new_host_key). Without a password anyone on your network could use that button to trust an impostor, so it is only offered with one. That protects against a host being swapped for an impostor after first contact, so if you want certainty about the first connection, compare the fingerprint with ssh-keyscan -t ed25519 <host> | ssh-keygen -lf -. Use a dedicated, unprivileged user, and keep it on a network you trust.
• Some tools change things. confirm_selected_choices adds movies and starts downloads, manage_stalled_downloads with PURGE_STALLED deletes the torrents you agreed to after an AUDIT, with their files, and the job runner triggers searches. Claude Desktop asks for your permission before it uses a tool, so review what it proposes.
• The image runs as a non-root user (UID 65532); see read-only and non-root operation to lock it down further.

Development

npm installnpm start           # MCP server (stdio) + dashboard on WEB_PORTnpm test            # the test suitenpx tsc --noEmit    # typecheck the backend and the tests

The dashboard is a separate npm project in web/ (React, Vite and TypeScript, with its own package.json):

cd webnpm installnpm run dev         # dev server on :5173, proxies /api to the backend on :3000npx tsc --noEmitnpm run build       # static assets the backend serves; the Dockerfile does this for you

Tests use Node's built-in test runner, so there is nothing extra to install. They run against a throwaway database, never read your real .env, have your service credentials removed from the environment, and fail every HTTP request unless a test installs a fake, so running them can't touch your real services. test/isolation.test.ts fails the run if any of that ever breaks.

Runtime notes

• State (settings, job history, the login secret) is a SQLite database at data/plex_director.db, or /app/data in the container.
• Uses the official MCP SDK.
• The Query chat calls the Anthropic API with the tools above; nothing else leaves your network except calls to TMDb and, if you set it, Discord.

CI/CD

.github/workflows/ci.yml has three jobs:

• Typecheck & audit (check) runs on every push and pull request against main: the TypeScript typecheck, the test suite, npm audit --audit-level=high, and the same typecheck and audit for the dashboard in web/.
• Build, smoke test, and publish (publish) runs on every push to main, every v*.*.* tag push and every pull request, once check passes. Every run builds the image and boots it with dummy configuration to confirm it starts. Pushes then publish to both registries (branch pushes tag latest and the commit SHA; tag pushes also get the version, e.g. 1.2.3 and 1.2), run a Docker Scout vulnerability scan (reported in the job summary, non-blocking for now), and sign both images with cosign.
• Create GitHub Release (release) runs only on v*.*.* tag pushes, after publish succeeds, and creates a release with generated notes.

Alongside it: CodeQL analyses the TypeScript on every push and pull request and weekly, OpenSSF Scorecard scores the repo's supply-chain practices weekly (see the badge above), and Dependabot opens weekly PRs for npm, Docker base image and GitHub Actions updates, which auto-merge once CI passes unless they are a major version bump.

License

MIT