plex-director-mcp
Plex Director is a self-hosted MCP server (with a web dashboard) that lets Claude query and manage a Plex + Servarr media stack, inspect downloads/indexers, run batch upgrade jobs, and monitor hosts.
Search your library: search Plex movies and shows by genre, actor, title, year, library (e.g. 4K), network/studio, rating, watch state, or recency with paging and sorting (
search_plex_library).Find episodes and what to watch next: search individual episodes by title, plot (with a show), air date, or premiere/finale (
search_episodes), and get Plex On Deck / Continue Watching (get_on_deck).Compare owned vs. missing: pull an actor's TMDb filmography and mark which titles are in Plex (
resolve_actor_filmography).Check TV completeness in Sonarr: per-show downloaded vs. missing aired episodes (
check_series_completeness), which shows have gaps (find_series_gaps), show status/quality/next airing (check_series_status), why episodes are missing (diagnose_missing_episodes), upcoming episodes (get_upcoming_episodes), and shows by downloaded quality (find_series_by_quality).Check and diagnose movies in Radarr: whether a movie exists and is monitored (
check_movie_status) and why it is missing via metadata, history, and queues (diagnose_missing_media).Add movies: search TMDb and show a choice grid (
search_and_select_movies), then add chosen titles to Radarr with a download search (confirm_selected_choices).Manage downloads and indexers: audit or purge stalled/slow qBittorrent torrents by hash (
manage_stalled_downloads) and check Prowlarr indexer health and warnings (check_indexer_health).Run batch jobs: plan a movie upgrade batch (
plan_media_upgrade), list jobs (get_background_jobs), pause/resume/cancel (update_job_status), and step a job manually (execute_next_job_step), with a rate-limited automatic runner.Monitor infrastructure: CPU, RAM, disk, uptime, and Docker health over SSH (
get_cluster_infrastructure_health,get_cluster_hardware_analytics), plus trusting a rebuilt host's new SSH key (trust_new_host_key) and triggering Radarr/Sonarr/Prowlarr backups (run_cluster_backup).View Plex/Tautulli analytics: live streams and transcoding load (
get_plex_activity) and watch statistics, top users, platforms, and libraries (get_library_analytics).
Note: several tools change state (adding movies, purging torrents, running backups, starting searches), so they should be confirmed with the user first.
Sends optional status notifications for completed batch jobs via a Discord webhook.
Monitors Docker health on remote hosts as part of cluster infrastructure checks.
Provides tools for checking active Plex streams, recent library usage, and diagnosing missing media in a Plex library.
Provides tools for managing stalled or low-speed downloads in qBittorrent.
Enables checking movie status in Radarr and diagnosing why a movie is missing from the library.
Enables managing TV show media availability and diagnosing missing content through Sonarr.
Monitors remote Ubuntu hosts over SSH for CPU, memory, and Docker health.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@plex-director-mcp Why is the latest episode of Severance missing from Plex?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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. SetWEB_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.
Related MCP server: TheBoringMCP
Contents
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-stoppeddocker compose up -dThen 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):
Registry | Image |
Docker Hub |
|
GitHub Container Registry |
|
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.
Architecture | Available |
x86-64 ( | ✅ |
arm64 ( | ✅ |
Image tags
Tag | Description |
| The most recent build of the |
| A specific release. Pin one of these if you want to choose when to upgrade. |
| The newest patch release of a minor version. |
| The build of one specific commit, for pinning or bisecting. |
Release notes for the numbered versions are on the Releases page.
Application setup
Start the container with one of the usage examples and open the web UI at
http://<host>:3000.Set a password. Add
WEB_PASSWORDto 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.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.
Give the chat box a brain. The Query page uses Claude to answer questions, so it needs
ANTHROPIC_API_KEYin 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.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:
Service | What to enter |
Radarr, Sonarr, Prowlarr | The URL, and the API key from Settings → General. |
SABnzbd | The URL, and the API key from Config → General. |
qBittorrent | The Web UI URL, username and password. |
Tautulli | The URL (without |
Plex | The server URL (e.g. |
TMDb | Your API Read Access Token (the long one, from your TMDb account's API settings), not the short v3 API key. |
Networking: inside the container,
localhostis the container itself, not your server. Use the LAN address of each service (for examplehttp://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-stoppedThe 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.envThen start it:
docker compose up -dDocker 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:latestAdd 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-fileis not the same as a.envfile 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 keybecomes the valueabc # 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:
-iis required, since MCP talks over stdin/stdout. Don't add-t.No
-pis 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.
Parameter | Function |
| The web dashboard. Change the left number to use a different port on your host. |
| Password for the web dashboard. Strongly recommended. |
| Enables the Query chat. |
| Service connection details; see the reference. Optional, since they can be entered on the Settings page. |
| The SQLite database: your saved settings, job history and login-session secret. Mount a volume here. |
| Optional. A private SSH key for host monitoring (with |
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.
Variable | Description |
| Radarr. Used for movie status, diagnosis, adding movies, and batch jobs. |
| Optional. The name of the quality profile new movies get when you add them. Leave it blank to use Radarr's first profile. Also on the Radarr tab of the Settings page. |
| Sonarr. Optional; used for TV episode completeness and backups. |
| Prowlarr, for indexer health and backups. |
| SABnzbd, for the queue and for diagnosing missing media. |
| qBittorrent Web UI. |
| Tautulli, for streams and watch statistics. |
| Plex, for searching what you own. |
| Optional. Comma-separated Plex library names to leave out of searches (whole names, any case), e.g. |
| TMDb API Read Access Token, for actor filmographies and the movie-choice grid. |
| Comma-separated hosts to monitor over SSH, e.g. |
| The SSH user for those hosts. |
Container settings. These are read from the environment every time and are never stored in the database or shown on the Settings page.
Variable | Default | Description |
| (none) | Requires a login for the dashboard. Changing it signs everyone out. |
| (none) | Only matters without |
| (none) | The reverse proxy in front of the dashboard: its address or subnet, comma-separated (e.g. |
| (none) | Encrypts the service credentials saved in the database (AES-256-GCM). 32 random bytes, base64 or hex: make one with |
|
| The port the dashboard listens on inside the container. |
| (none) | Anthropic API key for the Query chat. |
| (none) | Path (inside the container) to the private key for host monitoring. It must be readable by the container's user. |
| (none) | The passphrase, if that private key is passphrase-protected. |
| (none) | Discord webhook for job-completed and job-paused notifications. |
|
| How often the job runner advances a started job by one movie (minimum |
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:3000Or 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-director
docker compose up -d
docker image pruneDocker 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 pruneVerify 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:latestBuilding 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-passwordSee 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 # notemakes 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.
Page | What it shows |
Query | A chat box that answers questions about your library using Claude and your services. Search results appear as a table with posters (shows add seasons, episodes and watch progress), showing the first 50 with a button to expand. Follow-up questions keep the context; New chat starts over. Needs |
Server Status | Live Plex streams and watch statistics (from Tautulli). |
Node Utilization | CPU, memory, disk, uptime and container health for each SSH host. A host that is unreachable shows why; a host whose SSH key changed is flagged with a Trust new key button (see Security). |
Queues | The SABnzbd and qBittorrent download queues. |
Indexers | Every Prowlarr indexer with its status (healthy, recent failures, backing off, disabled) and Prowlarr's own health warnings. |
Jobs | Batch jobs and their progress. Read-only: start, pause and cancel jobs from Claude. |
Settings | Connection details for every service. Secrets are never sent back to the browser, only whether they are set. |
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
Tool | What it does |
★ | Searches the movies and TV shows in your Plex library by genre, actor, title, year and/or library (e.g. |
★ | Finds individual TV episodes: "the episode of Entourage where…", an episode by title, episodes that aired in a date range, a show's season premieres or finales. With a show named it searches the episode titles and plots; without one only titles and air dates, because Plex cannot search plots across the whole library. Shows the season and episode numbers, air date and watch state. |
★ | "What should I watch next?" from Plex's On Deck (Continue Watching): the movies you have partly played and, for each show you are following, the episode to watch next (or the one you are part way through), most recently active first, with how far through each is. A movie held in HD and 4K is one entry. Can be limited to movies or shows, or to a library such as |
★ | An actor's TMDb filmography, movies and TV shows (or only one), with each title marked as in Plex or not, filterable by year range, owned/missing, and library. Shows are matched to Plex by TMDb id, so a Plex show with no TMDb match is not recognised as owned. |
★ | "Do I have every episode of this show?" From Sonarr's episode list: how many aired episodes are downloaded, which seasons and episodes are missing, what has not aired yet, and whether Sonarr is monitoring the show (so will fetch the rest). Counts the episodes themselves rather than Sonarr's statistics, which treat a partly downloaded, unmonitored show as complete. It does not check what Plex has scanned. |
★ | Which TV shows are missing aired episodes, most missing first, with how many are downloaded and whether Sonarr is looking for the rest. Filter by monitored, not monitored or actively being searched for, by how many are missing (for "nearly complete" shows) and hide shows with nothing downloaded. |
★ | Finds TV shows by the video quality Sonarr downloaded: "which shows do I only have in 720p?", "which have 1080p or better?", "which mix qualities?" (upgrade candidates). Shows the lowest best quality first with how many files are at each resolution. It sees only what Sonarr downloaded, so a 4K copy in a separate Plex 4K library is not counted (use the Plex search with the |
★ | What Sonarr knows about one show: monitored or not, its quality profile and location, when the next episode airs, when something was last downloaded, what is in the download queue, and how many aired episodes are downloaded. |
★ | Why aired episodes of a show have no file, from Sonarr's history and download queue: never grabbed, grabbed but never imported, a download that failed (with Sonarr's reason), a file that was removed, stuck in the queue, or simply not monitored so Sonarr never looks for it. Can be limited to a season or one episode. Read-only. |
★ | What TV is coming, from Sonarr's calendar. With no title: "what's on this week?", every episode airing in the next few days (7 by default, up to 60) from the shows Sonarr monitors, by day, with season premieres and finales flagged and episodes already downloaded marked. With a title: "when does this show come back?", its next episodes, or that none is scheduled yet, or that it has ended. Shows Sonarr does not monitor are left out unless asked for, and their number is reported. |
★ | Whether a movie is in Radarr, and its monitoring status, with artwork. |
★ | Traces a movie through Radarr metadata, history and the download queues to find why it is missing. |
| Searches TMDb and shows a numbered grid of matches. |
| Adds the chosen numbers from that grid to Radarr as monitored movies and starts a download search. Already-present movies are reported, not added twice. Uses the quality profile you name, otherwise the default set on the Radarr tab of the Settings page, otherwise Radarr's first profile; and Radarr's first root folder unless you name another. |
Downloads and indexers
Tool | What it does |
|
|
| Reports failing, backing-off and disabled Prowlarr indexers, and Prowlarr's own warnings. |
Background jobs
Tool | What it does |
| Finds movies without a file or below 1080p and schedules them as a batch job (movies only, up to 25 at a time by default). |
| Lists jobs and their progress. |
|
|
| Searches the next movie in a job by hand. Started jobs are also advanced automatically, one movie a minute, by the job runner. |
Infrastructure and analytics
Tool | What it does |
| CPU, memory and Docker container health for each SSH host. |
| CPU and memory per host as a table. |
| Forgets a monitored host's remembered SSH key after you rebuilt it, so the next check trusts the key it presents now. The dashboard's Trust new key button does the same, but only when |
| Asks Radarr, Sonarr and Prowlarr (whichever are configured) to run their built-in database backups, waits for each (up to about a minute; a slower one is reported as still running), and confirms a new backup file appeared, with its name, size and time. The backups stay in each app's own backup folder; nothing is copied. |
| Live playback streams and transcoding load, via Tautulli. |
| Most-watched titles, top users, platforms and libraries, via Tautulli. |
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 usetrust_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 withssh-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_choicesadds movies and starts downloads,manage_stalled_downloadswithPURGE_STALLEDdeletes the torrents you agreed to after anAUDIT, 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 install
npm start # MCP server (stdio) + dashboard on WEB_PORT
npm test # the test suite
npx tsc --noEmit # typecheck the backend and the testsThe 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 youTests 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/datain 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 againstmain: the TypeScript typecheck, the test suite,npm audit --audit-level=high, and the same typecheck and audit for the dashboard inweb/.Build, smoke test, and publish (
publish) runs on every push tomain, everyv*.*.*tag push and every pull request, oncecheckpasses. Every run builds the image and boots it with dummy configuration to confirm it starts. Pushes then publish to both registries (branch pushes taglatestand the commit SHA; tag pushes also get the version, e.g.1.2.3and1.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 onv*.*.*tag pushes, afterpublishsucceeds, 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
Available Tools
26 toolscheck_indexer_healthA
Audits all Usenet indexers and torrent trackers configured in Prowlarr to flag connection failures or bans, and reports Prowlarr's own system health warnings.
Inputs: no named parameters.
check_movie_statusA
Checks if a specific movie exists in the Radarr library on the Ubuntu cluster and returns its monitoring status with artwork.
Inputs: title (required).
check_series_completenessA
Answers 'do I have every episode of ?' from Sonarr's episode list: how many aired episodes are downloaded, which seasons and episodes are missing, what has not aired yet, and whether Sonarr is monitoring the show (so will fetch the rest). Use this for one specific TV show; use find_series_gaps to see which shows have gaps. It does not check what Plex has scanned.
Inputs: title (required), year.
check_series_statusA
The TV counterpart of check_movie_status: what Sonarr knows about one show - whether it is monitored, its quality profile and location, when the next episode airs, when something was last downloaded, what is in the download queue, and how many aired episodes are downloaded. Use it for 'is monitored?', 'what quality is ?', 'when does come back?'. For which episodes are missing use check_series_completeness; for why one is missing use diagnose_missing_episodes.
Inputs: title (required), year.
confirm_selected_choicesA
Adds the user's numbered choices from the last search_and_select_movies grid to Radarr as monitored movies and starts a download search for each. Movies already in Radarr are reported, not added twice. Uses the quality profile you name, otherwise the default set on the Settings page, otherwise Radarr's first quality profile; and Radarr's first root folder unless told otherwise.
Inputs: chosenIndexes (required), rootFolder, qualityProfile.
diagnose_missing_episodesA
Explains WHY aired episodes of a show have no file, the TV counterpart of diagnose_missing_media: from Sonarr's history and download queue it says, per group of episodes, whether they were never grabbed, were grabbed but never imported, had a download fail (and why), had their file removed, are stuck in the queue, or are simply not monitored so Sonarr never looks for them. Read-only: it changes nothing. Give season (and episode) to look at just those; without them it groups every missing episode of the show. Use check_series_completeness first to see which episodes are missing.
Inputs: title (required), year, season, episode.
diagnose_missing_mediaA
Traces a movie through Radarr metadata, history, and active download client queues to pinpoint why it is missing.
Inputs: title (required).
execute_next_job_stepA
Processes a single sequential block item from an active background batch queue entry to prevent API flooding. (Jobs that have been started are also advanced automatically, one item per minute, by the job runner.)
Inputs: jobId (required).
find_series_by_qualityA
Finds TV shows by the video quality Sonarr downloaded: 'which shows do I only have in 720p?' (bestAtMost 720), 'which shows have 1080p or better?' (bestAtLeast 1080), 'which shows mix qualities?' (mixedOnly, useful as upgrade candidates). Lists the shows with the lowest best quality first, each with how many files are at each resolution, and opens with how many shows are at each level. It only sees what Sonarr downloaded, so a 4K copy in a separate Plex 4K library that Sonarr does not manage is not counted: for 4K use search_plex_library with library '4k'. Use folder to narrow to a kind of show by its Sonarr folder ('kids', 'anime', 'sports'). The first call reads every show's files (about 15 seconds) and is then cached for 5 minutes. Read-only.
Inputs: limit, folder, mixedOnly, monitored, +2 more.
find_series_gapsA
Lists the TV shows in Sonarr that are missing aired episodes, most missing first, with how many are downloaded, whether Sonarr is monitoring each show, and whether it is actively looking for the rest. Use it for 'which of my shows have gaps?', 'what am I missing?' or 'which shows are only missing a few episodes?'. Use monitored 'searching' for 'what is Sonarr still looking for?'. Express any narrowing as a filter (monitored, minMissing, maxMissing, hideEmpty) rather than filtering the result yourself, because the table shown to the user is exactly the rows returned. Most gaps are in shows that are deliberately not monitored or only partly kept; 'hideEmpty' drops shows with nothing downloaded and 'maxMissing' finds near-complete ones. For one show use check_series_completeness.
Inputs: limit, hideEmpty, monitored, maxMissing, +1 more.
get_background_jobsA
Retrieves active, pending, or completed persistent media processing jobs running on the server cluster.
Inputs: no named parameters.
get_cluster_hardware_analyticsA
Fetches real-time CPU load and memory allocation for every configured cluster host over SSH, as a Markdown table.
Inputs: no named parameters.
get_cluster_infrastructure_healthA
Collects real-time CPU utilization, RAM usage, and active Docker container counts across all configured Ubuntu hosts.
Inputs: no named parameters.
get_library_analyticsA
Queries historical statistics regarding most watched movies, total user count, and overall watch metrics.
Inputs: no named parameters.
get_on_deckA
Answers 'what should I watch next?' from Plex's On Deck ('Continue Watching'): the movies the user has partly played and, for each show they are following, the episode to watch next (or the one they are part way through), most recently active first, with how far through each one is. A movie held in HD and 4K is one entry. Use title for 'which episode is next for ?' and mediaType 'show' for 'which episode is next in each show?'. IMPORTANT: On Deck is only Plex's short recent list (at most 50 items across everything), not every unfinished title, so for 'which movies did I start but not finish?', 'what haven't I finished?' or any complete list use search_plex_library with watched 'inProgress' instead. The watch state is for the Plex account the app is connected with.
Inputs: limit, title, library, mediaType.
get_plex_activityA
Fetches real-time playback streaming analytics from Plex via Tautulli to monitor user context and transcoding strain.
Inputs: no named parameters.
get_upcoming_episodesA
What TV episodes are coming, from Sonarr's calendar. With no title it answers 'what's on this week?': every episode airing in the next few days (default 7, up to 60) from the shows Sonarr monitors, by day, with season premieres and finales flagged and episodes already downloaded marked. With a title it answers 'when does come back?': that show's next episodes, or that none is scheduled yet (or that it has ended). Only shows Sonarr monitors are listed by default and the number left out is reported; use monitored 'unmonitored' when the user asks about shows they do not monitor, or 'any' for everything (express that as the filter, because the table shown to the user is exactly the rows returned). Dates are the network's own air dates.
Inputs: days, year, title, monitored.
manage_stalled_downloadsA
Lists qBittorrent downloads that are stalled or slower than a threshold (AUDIT), and deletes chosen ones with their downloaded files (PURGE_STALLED). PURGE_STALLED only deletes the torrents whose hashes you pass, taken from an AUDIT the user has seen and agreed to; it never deletes anything else, and Radarr and Sonarr are not told.
Inputs: action (required), hashes, minSpeedKbps.
plan_media_upgradeC
Evaluates and safely schedules a controlled batch upgrade for specified media classes while enforcing storage policies.
Inputs: mediaType (required), targetResolution (required), maxBatchSize.
resolve_actor_filmographyA
Resolves an actor's name to their official TMDb filmography (movies and TV shows), filtering out talk shows, news, self-appearances, and uncredited roles. When Plex is configured, marks which of those titles the user already has in their Plex library and which they don't. Use this to answer which of an actor's movies or shows the user is missing. Pass mediaType 'movie' when the user asks about movies/films, 'show' for TV/series, and leave it out (any) when the question is about the actor's work in general; keep the same mediaType on follow-ups.
Inputs: actorName (required), show, limit, yearTo, +3 more.
run_cluster_backupA
Asks each configured Servarr app (Radarr, Sonarr, Prowlarr) to create its built-in database backup, waits for each to finish, and confirms a new backup file appeared, reporting the file's name, size and time. The backups stay in each app's own backup folder; nothing is copied.
Inputs: no named parameters.
search_and_select_moviesA
Searches TMDb for matching movies and renders a structured Markdown multi-choice grid interface for confirmation.
Inputs: query (required).
search_episodesA
Finds individual TV episodes in the user's Plex library: 'the episode of where ...', 'which episode is called ...', episodes that aired in a date range, a show's season premieres or finales. IMPORTANT: Plex cannot search episode plots across the whole library. To search PLOTS (summaries) you must name the show (the show argument); the words then match the episode title and its plot. Without a show, only episode TITLES (and air dates) can be searched. When the user describes an episode by its plot and no show is known, ask which show or say only titles can be searched. Use season and episode for a specific one, airedFrom/airedTo (YYYY-MM-DD) for 'aired in March 2026', and episodeType 'premiere' or (with a show) 'finale'. Each result shows the show, season and episode numbers, air date and watch state.
Inputs: show, text, limit, season, +5 more.
search_plex_libraryA
Searches the movies and TV shows actually in the user's Plex library (across all movie and show libraries, including 4K) by genre, actor, title, release year, and/or library. Filters can be combined, e.g. genre 'Horror' with year 1982, or genre 'Horror' with library '4k'. Pass mediaType 'movie' when the user asks about movies/films, 'show' for TV/series/shows, and leave it out (any) when the question is about titles in general, e.g. everything with an actor; a show in several libraries is one result, with its season and episode counts. Some libraries (such as Sports) may be left out unless named in the library filter. Use this to answer what the user owns or can watch; use check_movie_status for Radarr/download status of one specific movie. Watch state: use watched 'unwatched' (never played), 'inProgress' (started but not finished - this is the complete list of unfinished titles, unlike get_on_deck's short recent list) or 'watched' (finished), and notWatchedInYears for 'haven't watched in N years' (a never-watched title counts from when it was added); they are for the Plex account the app is connected with. sort orders by recentlyAdded, lastWatched or leastRecentlyWatched instead of by title. Also filter by network (or movie studio), contentRating (TV-MA, R...), minRating (audience rating 0-10), yearFrom/yearTo (a decade is 1990 to 1999) and addedWithinDays ('what showed up this week?'). Plex does not know whether a show is continuing or ended; use Sonarr tools for that. Always express a narrowing the user asks for (4K, a genre, a year, unwatched...) as a filter here rather than filtering results yourself, because the results table shown to the user contains exactly the rows this returns. The default limit is small: when the user wants everything ('all', 'every', 'list them'), pass limit 500; if the reply says more matches remain, call again with the offset it gives.
Inputs: sort, year, actor, genre, +13 more.
trust_new_host_keyA
Forgets the remembered SSH key of a monitored host so the next check trusts the key it presents now. Only for a host the user rebuilt or reinstalled: an unexpected key change can mean another machine is impersonating it. Confirm with the user first.
Inputs: host (required).
update_job_statusA
Updates the operational state of an active or pending background batch job.
Inputs: jobId (required), action (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 26 tools
Most tools are clearly separated by their descriptions, especially across Plex discovery, Sonarr episode diagnostics, Radarr movie status, and job control. However, get_cluster_infrastructure_health and get_cluster_hardware_analytics overlap heavily, and the background job tools require careful reading to distinguish retrieval, update, and step execution.
All tool names use snake_case and overwhelmingly follow predictable verb_noun or verb_noun_phrase patterns such as check_*, get_*, find_*, diagnose_*, and search_*. Minor outliers like get_on_deck and search_and_select_movies remain readable and do not break the overall convention.
At 26 tools, the surface is heavy and sits just above the rubric's 25+ 'too many' threshold. The broad server scope across Plex, Radarr, Sonarr, Prowlarr, qBittorrent, cluster infrastructure, and background jobs justifies many tools, but some consolidation—especially around cluster metrics and job control—would improve scoping.
The server covers diagnostics, status checks, search, backups, and movie-addition workflows well, but there are notable lifecycle gaps. There is no tool to add or monitor TV series, no general update/delete capability for Radarr/Sonarr/Plex items, and no media removal beyond stalled torrents.
Maintenance
Related MCP Connectors
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Uptime, SSL, DNS and domain monitoring you can talk to from Claude or any MCP client.
Live SEO workflow tools for Claude Code, Codex, and AI agents.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables full management of a Plex Media Server via Claude, including browsing libraries, fixing metadata, managing collections, and more.-
- AlicenseNot gradedqualityBmaintenanceEnables control of a home lab through a single MCP server, exposing tools for Home Assistant, Portainer, Sonarr, Radarr, SABnzbd, and Jellyfin so Claude can query states, manage containers and stacks, handle media libraries and download queues, and run automations. Each service is optional and can be configured via environment variables, with a read-only mode and bearer-token-protected HTTP transport for always-on deployments.1MIT
- AlicenseAqualityBmaintenanceEnables Claude to monitor and manage a self-hosted media stack—including Sonarr, Radarr, Prowlarr, Bazarr, Overseerr, qBittorrent, and Jellyfin—through tools for status, queues, searches, additions, requests, downloads, and now-playing checks. It also supports arbitrary API calls with safety levels and secret redaction.13MIT
- AlicenseAqualityBmaintenanceEnables Claude and other MCP clients to query, troubleshoot, and manage Sonarr, Radarr, and Prowlarr, including guided diagnostics, safe maintenance, and bulk actions with good-practice guardrails.361MIT