plex-director-mcp

# plex-director-mcp

[![CI/CD](https://github.com/HoneyBearTech/plex-director-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/HoneyBearTech/plex-director-mcp/actions/workflows/ci.yml)
[![CodeQL](https://github.com/HoneyBearTech/plex-director-mcp/actions/workflows/codeql.yml/badge.svg)](https://github.com/HoneyBearTech/plex-director-mcp/actions/workflows/codeql.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/HoneyBearTech/plex-director-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/HoneyBearTech/plex-director-mcp)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/15521/badge)](https://www.bestpractices.dev/projects/15521)
[![OpenSSF Baseline](https://www.bestpractices.dev/projects/15521/baseline)](https://www.bestpractices.dev/projects/15521)
[![Docker Pulls](https://img.shields.io/docker/pulls/honeybeartech/plex-director-mcp?logoColor=white&logo=docker)](https://hub.docker.com/r/honeybeartech/plex-director-mcp)
[![Docker Version](https://img.shields.io/github/v/tag/HoneyBearTech/plex-director-mcp?sort=semver&logo=docker&logoColor=white&label=version)](https://hub.docker.com/r/honeybeartech/plex-director-mcp/tags)
[![Image Size](https://img.shields.io/docker/image-size/honeybeartech/plex-director-mcp/latest?logo=docker&logoColor=white)](https://hub.docker.com/r/honeybeartech/plex-director-mcp)
[![Node](https://img.shields.io/badge/node-24-339933?logo=node.js&logoColor=white)](package.json)
[![License](https://img.shields.io/github/license/HoneyBearTech/plex-director-mcp)](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](docs/security.md).

## Documentation

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

## Contents

- [Documentation](#documentation)
- [What it can do](#what-it-can-do)
- [Quick start](#quick-start)
- [Docker](#docker)
  - [Supported architectures](#supported-architectures)
  - [Image tags](#image-tags)
  - [Application setup](#application-setup)
  - [Usage](#usage) — [Docker Compose](#docker-compose-recommended) · [Docker CLI](#docker-cli) · [Claude Desktop via Docker](#claude-desktop-via-docker)
  - [Parameters](#parameters)
  - [Environment variable reference](#environment-variable-reference)
  - [Read-only and non-root operation](#read-only-and-non-root-operation)
  - [Updating](#updating)
  - [Building locally](#building-locally)
- [Run without Docker (Claude Desktop)](#run-without-docker-claude-desktop)
- [Web dashboard](#web-dashboard)
- [MCP tools](#mcp-tools)
- [Security](#security)
- [Development](#development)
- [CI/CD](#cicd)
- [License](#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](https://registry.modelcontextprotocol.io/) as `io.github.HoneyBearTech/plex-director-mcp`, so MCP clients that browse the registry can install it directly ([`server.json`](server.json) lists its settings). Otherwise, the fastest way to try it is Docker Compose:

```yaml
---
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
```

```bash
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](#docker) below. To use it from Claude Desktop instead, see [Claude Desktop via Docker](#claude-desktop-via-docker).

## Docker

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

| Registry | Image |
| :--- | :--- |
| Docker Hub | `honeybeartech/plex-director-mcp` |
| GitHub Container Registry | `ghcr.io/honeybeartech/plex-director-mcp` |

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 (`linux/amd64`) | ✅ |
| arm64 (`linux/arm64`) | ✅ |

### Image tags

| Tag | Description |
| :---: | :--- |
| `latest` | The most recent build of the `main` branch. Includes changes that have not been given a version number yet. |
| `1.2.0` | A specific release. Pin one of these if you want to choose when to upgrade. |
| `1.1` | The newest patch release of a minor version. |
| `sha-<commit>` | The build of one specific commit, for pinning or bisecting. |

Release notes for the numbered versions are on the [Releases](https://github.com/HoneyBea