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.

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 (25 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

By default the container runs as root, which lets it write to whatever you mount at /app/data. The image itself has no shell or package manager. If you would rather it didn't run as root, or want a read-only filesystem, both work; the data directory is the only place it writes, so it just has to be writable by the user you choose.

services:
  plex-director:
    image: honeybeartech/plex-director-mcp:latest
    user: "1000:1000"
    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: --user 1000:1000 --read-only --cap-drop ALL --security-opt no-new-privileges:true.

Make sure the data directory is writable by that user first, for example chown -R 1000:1000 /path/to/plex-director/data (a Docker-created named volume is owned by root). If it is not, the container exits at startup with SqliteError: unable to open database file. If you use SSH host monitoring, the mounted key must also be readable by that user.

Updating

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

Docker Compose

docker compose pull plex-director
docker compose up -d
docker image prune

Docker CLI

docker pull honeybeartech/plex-director-mcp:latest
docker stop plex-director
docker rm plex-director
# ...then run the same `docker run` command as before
docker 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.git
cd plex-director-mcp
docker 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.git
cd plex-director-mcp
npm 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:7878
RADARR_API_KEY=your_radarr_api_key
RADARR_DEFAULT_QUALITY_PROFILE=Your Profile Name
SONARR_URL=http://sonarr:8989
SONARR_API_KEY=your_sonarr_api_key
PROWLARR_URL=http://prowlarr:9696
PROWLARR_API_KEY=your_prowlarr_api_key
SABNZBD_URL=http://sabnzbd:8080
SABNZBD_API_KEY=your_sabnzbd_api_key
QBITTORRENT_URL=http://qbittorrent:8080
QBITTORRENT_USER=your_qbittorrent_user
QBITTORRENT_PASS=your_qbittorrent_password
TAUTULLI_URL=http://tautulli:8181
TAUTULLI_API_KEY=your_tautulli_api_key
PLEX_URL=http://plex:32400
PLEX_TOKEN=your_plex_token
TMDB_API_KEY=your_tmdb_read_access_token
ANTHROPIC_API_KEY=your_anthropic_api_key
UBUNTU_HOSTS=192.168.1.10,192.168.1.11
SSH_USER=your_ssh_username
SSH_KEY_PATH=/path/to/id_ed25519
SSH_KEY_PASSPHRASE=only_if_the_key_has_one
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
WEB_PORT=3000
WEB_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-five 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 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 torrents and 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 root by default; see read-only and non-root operation to lock it down.

Development

npm install
npm start           # MCP server (stdio) + dashboard on WEB_PORT
npm test            # the test suite
npx 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 web
npm install
npm run dev         # dev server on :5173, proxies /api to the backend on :3000
npx tsc --noEmit
npm 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