Plex Director

plex-director-mcp

Plex Director 是一款适用于 Plex + Servarr 媒体栈的可自托管助手。它连接 Plex、Radarr、Sonarr、Prowlarr、SABnzbd、qBittorrent、Tautulli 和 TMDb（也可选择通过 SSH 连接你的 Linux 主机），并提供两种使用方式：

• 面向 Claude Desktop 的 MCP 服务——让 Claude 帮你查找已有的内容、分析电影缺失的原因、添加电影、检查索引器和下载队列，或运行批处理任务。
• Web 仪表板——提供浏览器界面和聊天框（“我有 Harrison Ford 的哪些 4K 电影？”）、服务状态、主机资源利用率、下载队列、索引器运行状况和后台任务。

它专为家庭环境设计：在局域网上运行，放在它所连接的应用旁边即可。

警告

Plex Director 持有你所连接的每项服务的 API 密钥，不仅能读取数据，也能修改数据：它会将电影添加到 Radarr 并启动下载搜索、从 qBittorrent 中移除停滞的种子、运行批量升级任务，以及触发 Servarr 备份。添加电影前需要先选择再确认，批处理任务也会在运行前规划；但清除停滞的种子和启动备份会在收到请求后立即执行，聊天界面和 Claude Desktop 也会使用你的密钥。请设置 WEB_PASSWORD，不要将仪表板暴露在公共互联网上，并查看安全要求。

文档

• 快速入门、安装、升级和备份以及验证发行版本。
• 用户指南：仪表板页面、Query 聊天和 MCP 工具。文档索引列出了所有内容。
• 架构：各个组件、它们的使用者，以及问题如何在组件之间流转。
• 安全要求：Plex Director 能防护和无法防护的风险，以及背后的保证论证。
• 路线图：项目的发展方向，以及它不会做什么。
• 无障碍：仪表板目前支持的内容和已知不足。
• 外部接口（仪表板的 HTTP API 见 docs/api/openapi.json）以及依赖项和漏洞管理。
• 支持：哪些版本会获得修复，以及支持期限。变更日志。
• 贡献指南、行为准则、治理以及报告漏洞。

目录

• 文档
• 功能
• 快速入门
• Docker
  • 支持的架构
  • 镜像标签
  • 应用设置
  • 用法 — Docker Compose · Docker CLI · 通过 Docker 使用 Claude Desktop
  • 参数
  • 环境变量参考
  • 只读和非 root 运行
  • 更新
  • 本地构建
• 不使用 Docker 运行（Claude Desktop）
• Web 仪表板
• MCP 工具
• 安全
• 开发
• CI/CD
• 许可证

功能介绍

• 查找你拥有的内容。 按类型、演员、标题、年份和媒体库搜索 Plex 媒体库中的电影和电视节目，也可以一次搜索所有媒体库（例如只搜索 4K 媒体库）。同一部影片如果同时存在于高清和 4K 媒体库中，只会显示为一个结果，并列出两个媒体库；电视节目还会显示季数、集数和观看进度。除非你明确指定，否则可以将 Sports 等媒体库排除在搜索之外。
• 每集都齐了吗？ 询问某部剧，Sonarr 的剧集列表会显示已播出的剧集中有多少集已下载，并准确列出缺少哪些剧集；也可以询问哪些剧集尚有缺漏，并按缺漏情况排序，包括接近完整的剧集。尚未播出的剧集和特别篇永远不会计为缺失。对于缺失的剧集，还可以根据 Sonarr 的历史记录和下载队列说明原因。
• 最近播出什么，何时回归？ 查看未来几天播出的剧集，并标记首播和季终集；也可以询问某部剧何时回归（或是否尚未公布日期）。
• 接下来该看什么？ 询问待看内容：你正在追看的每部剧的下一集，以及尚未看完的电影，并显示每部电影的观看进度。
• 我看过什么，又有哪些内容已经搁置？ 查询未看过的剧集、开始看了却从未看完的剧集、几年没看过的电影，或最新添加的内容；可以单独查询，也可以结合类型、媒体库等条件查询。对于 Plex 标记为已观看但未记录日期的影片，会将其单独列出并计数，而不会猜测日期。
• 已拥有与缺失内容对比。 查询某位演员在 TMDb 上的电影作品列表，包括电影和电视节目，并查看哪些影片已在 Plex 中、哪些没有；还可以选择仅查看电影或剧集、按年份范围筛选，或筛选「4K」内容。会排除脱口秀节目和「本人」出演记录；即使演员在同一部影片中出演多个角色，也只会列出一次。
• 诊断并添加电影。 追踪电影的 Radarr 元数据、历史记录和下载队列，了解影片缺失的原因；也可以搜索 TMDb，从网格中选择影片，并将所选影片添加到 Radarr，同时搜索下载资源。
• 监控下载和索引器。 查看 SABnzbd 和 qBittorrent 队列、清理停滞的种子，并检查每个 Prowlarr 索引器的运行状况（包括正在退避的索引器）。
• 安全运行批量任务。 规划电影升级批次，并让受速率限制的运行器每分钟搜索一部电影；支持暂停、恢复、取消，并在 Radarr 停止响应时自动暂停。
• 监控主机。 通过 SSH 查看 Linux 主机的 CPU、内存、磁盘、运行时间和 Docker 容器健康状况，也可以按需查看 Radarr、Sonarr 和 Prowlarr 内置备份。每台主机首次连接时都会记住其 SSH 密钥；如果密钥发生变化，则会拒绝连接，直到你批准为止。
• 了解使用情况。 通过 Tautulli 查看 Plex 实时串流和观看统计信息。
• 及时了解动态。 批量任务完成或暂停时，可选择接收 Discord 通知。

快速开始

从 v1.2.0 起，Plex Director 已列入官方 MCP 注册表，标识为 io.github.HoneyBearTech/plex-director-mcp，因此可以浏览注册表的 MCP 客户端能够直接安装（其设置见 server.json）。除此之外，最快的试用方式是使用 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

然后打开 **http://localhost:3000**，登录并在 Settings 页面填写你的服务信息（Radarr、Sonarr、Prowlarr、SABnzbd、qBittorrent、Tautulli、Plex、TMDb）。包含所有选项的完整指南见下方的 Docker。若要通过 Claude Desktop 使用，请参阅 通过 Docker 使用 Claude Desktop。

Docker

镜像已发布到两个注册表，并且均已签名（参见 CI/CD）：

注册表	镜像
Docker Hub	honeybeartech/plex-director-mcp
GitHub Container Registry	ghcr.io/honeybeartech/plex-director-mcp

以下内容适用于任一镜像；示例使用 Docker Hub。

支持的架构

我们会发布多架构清单，因此拉取镜像时会自动获取适用于你设备的版本。

架构	可用
x86-64 (linux/amd64)	✅
arm64 (linux/arm64)	✅

镜像标签

标签	说明
latest	main 分支的最新构建版本，包含尚未分配版本号的更改。
1.4.0	特定发行版。如果你想自行选择升级时机，请固定使用其中一个版本。
1.1	某个次要版本中最新的补丁版本。
sha-<commit>	特定提交的构建版本，可用于固定版本或二分查找。

编号版本的发行说明请参阅 Releases 页面。

应用设置

1. 启动容器：使用用法中的示例之一，然后在 http://<host>:3000 打开 Web UI。
2. 设置密码。 将 WEB_PASSWORD 添加到容器的环境变量中。未设置时，任何能访问该端口的人都可以使用控制面板，包括 Settings 页面，并且页面会显示警告横幅。请参阅安全。
3. 添加服务。 打开 Settings 并填写各个选项卡。每个字段也可以通过环境变量设置（请参阅环境变量参考），这对自动化设置很方便。你只需配置实际使用的服务。
4. 为聊天框配置 AI。 Query 页面使用 Claude 回答问题，因此需要在容器的环境变量中设置 ANTHROPIC_API_KEY。这是按使用量付费的 Anthropic API 密钥，与 Claude 订阅分开。控制面板的其余部分无需此密钥也能正常工作。
5. 保留数据卷。 你的设置、任务历史记录以及用于保持登录状态的密钥都存储在 /app/data 下的 SQLite 数据库中。请在此处挂载数据卷，否则每次重新创建容器时都会丢失这些数据。

各项凭据的获取位置：

服务	填写内容
Radarr、Sonarr、Prowlarr	URL，以及 Settings → General 中的 API 密钥。
SABnzbd	URL，以及 Config → General 中的 API 密钥。
qBittorrent	Web UI URL、用户名和密码。
Tautulli	URL（不含 /api/v2），以及 Settings → Web Interface 中的 API 密钥。
Plex	服务器 URL（例如 http://192.168.1.10:32400）和 X-Plex-Token：在 Plex Web 中打开任意一部电影，选择 ⋯ → Get Info → View XML，然后从地址栏中复制 X-Plex-Token= 后面的值。请像密码一样妥善保管。
TMDb	你的 API Read Access Token（较长的那个，可在 TMDb 账户的 API 设置中找到），而不是较短的 v3 API 密钥。

**网络：**在容器内部，localhost 指的是容器本身，而不是你的服务器。请使用每个服务的局域网地址（例如 http://192.168.1.10:7878）；如果其他应用位于同一个 Compose 项目或 Docker 网络中，也可以使用它们的服务名称（http://radarr:7878）。

用法

以下示例片段可帮助你开始创建容器。推荐使用 Docker Compose。

Docker Compose（推荐）

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

镜像内置健康检查（容器启动后，docker ps 会显示 healthy），因此无需另行添加。

若要避免在 compose 文件中暴露凭据，请将它们放在旁边的 .env 格式文件中，并引用该文件，而不是逐项列出：

    env_file:
      - plex-director.env

然后启动：

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

你可以通过更多 -e 标志添加参考中的其他变量，也可以将它们放入文件并传入 --env-file plex-director.env。若要监控 SSH 主机，还要添加 -v /path/to/ssh/id_ed25519:/ssh/id_ed25519:ro。

**--env-file 与 Node 的 .env 文件不同。**Docker 会按原样读取值：不要在值两侧加引号，也不要在同一行的值后添加注释（KEY=abc # my key 会被读取为值 abc # my key）。请将注释放在单独一行。

通过 Docker 使用 Claude Desktop

同一镜像也可以作为 MCP 服务，通过 stdio 通信。让 Claude Desktop 在配置中使用 docker run -i 运行它（设置 → 开发者 → 编辑配置，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"
      ]
    }
  }
}

重启 Claude Desktop 后，plex-director 服务会作为工具提供方显示（共 26 个工具，见下文）。注意：

• 必须使用 -i，因为 MCP 通过 stdin/stdout 通信。不要添加 -t。
• 无需使用 -p。Web 仪表板也会在此容器中启动，但只有在想从此容器而不是 Compose 容器访问它时，才需要发布其端口。
• 如果也运行上面的长期运行容器，请为两者使用相同的数据卷（或绑定挂载），以便共享设置和作业历史记录。
• 如果 Claude 关闭 stdin，容器仍会继续运行；退出 Claude Desktop 会停止容器，也可以使用 docker stop。

参数

容器镜像通过运行时传入的参数进行配置。这些参数以冒号分隔，分别表示 <external>:<internal>。例如，-p 8080:3000 会将容器内部的端口 3000 暴露出来，使其可通过容器外部主机 IP 上的端口 8080 访问。

参数	功能
-p 3000:3000	Web 仪表板。更改左侧数字即可使用主机上的其他端口。
-e WEB_PASSWORD=	Web 仪表板的密码。强烈建议设置。
-e ANTHROPIC_API_KEY=	启用 Query 聊天功能。
-e RADARR_URL= 等	服务连接详情；请参阅参考。此项可选，也可以在设置页面中填写。
-v /app/data	SQLite 数据库：保存的设置、作业历史记录和登录会话密钥。请在此处挂载卷。
-v /ssh/id_ed25519:ro	可选。 用于主机监控的 SSH 私钥（配合 -e SSH_KEY_PATH=/ssh/id_ed25519 使用）。

环境变量参考

启动容器不需要任何配置：容器会在无配置的情况下启动，你可以在设置页面中填写相关信息。

服务连接。 首次启动时，这些值会复制到数据库中，此后以数据库中保存的值为准（设置页面编辑的就是这些值）。如果之后更改了其中一个变量却没有任何效果，原因就在这里；请在设置页面中更改，或删除数据库。

变量	说明
RADARR_URL、RADARR_API_KEY	Radarr。用于影片状态查询、诊断、添加影片和批量作业。
RADARR_DEFAULT_QUALITY_PROFILE	可选。 添加新影片时使用的画质配置文件名称。留空则使用 Radarr 中的第一个配置文件。也可以在设置页面的 Radarr 选项卡中设置。
SONARR_URL、SONARR_API_KEY	Sonarr。可选；用于检查电视剧集的完整性和进行备份。
PROWLARR_URL、PROWLARR_API_KEY	Prowlarr，用于索引器健康状态检查和备份。
SABNZBD_URL、SABNZBD_API_KEY	SABnzbd，用于队列管理和诊断缺失媒体。
QBITTORRENT_URL、QBITTORRENT_USER、QBITTORRENT_PASS	qBittorrent Web UI。
TAUTULLI_URL、TAUTULLI_API_KEY	Tautulli，用于查看流媒体播放和观看统计数据。
PLEX_URL、PLEX_TOKEN	Plex，用于搜索你拥有的媒体。
PLEX_SKIP_LIBRARIES	可选。 以逗号分隔的 Plex 媒体库名称，这些媒体库不会纳入搜索（完整名称，不区分大小写），例如 Sports。如果问题中提到某个媒体库，例如“在 Sports 中”，仍会搜索该媒体库。留空则搜索所有媒体库。也可以在设置页面的 Plex 选项卡中设置。
TMDB_API_KEY	TMDb API Read Access Token，用于查询演员作品目录和显示电影选择网格。
UBUNTU_HOSTS	以逗号分隔的主机列表，用于通过 SSH 进行监控，例如 192.168.1.10,192.168.1.11。非标准 SSH 端口可添加 :port（192.168.1.10:2222）。
SSH_USER	这些主机的 SSH 用户名。

容器设置。 每次都会从环境中读取这些设置，且绝不会存储在数据库中或显示在设置页面上。

变量	默认值	描述
WEB_PASSWORD	(none)	为仪表板启用登录。更改后会让所有人退出登录。
WEB_ALLOWED_HOSTS	(none)	仅在未设置 WEB_PASSWORD 时生效：仪表板会响应的额外主机名，以逗号分隔（例如，反向代理后的 plex.example.com）。IP 地址、localhost、单个词的名称以及 .local / .lan / .home.arpa / .internal 名称始终可用；其他名称会返回 403，以阻止 DNS 重绑定攻击。* 可关闭此检查。
WEB_TRUST_PROXY	(none)	仪表板前方的反向代理：填写其地址或子网，以逗号分隔（例如 192.168.40.10 或 192.168.40.0/24），也可填写 loopback。只有来自该代理的请求才能设置 X-Forwarded-For 和 X-Forwarded-Proto，这样登录次数限制会按真实客户端计算，且通过 HTTPS 访问时会话 Cookie 会设置为 Secure。未设置时，这两个请求头都会被忽略。true 和跳数会被拒绝。
SETTINGS_ENCRYPTION_KEY	(none)	加密保存在数据库中的服务凭据（AES-256-GCM）。需要 32 个随机字节，使用 base64 或 hex 编码：运行 openssl rand -base64 32 生成。已保存的凭据会在下次启动时加密。所有共用数据库的容器都必须使用相同的密钥；没有密钥，数据库将无法使用，因此请将密钥副本保存在备份之外的位置。建议设置。
WEB_PORT	3000	仪表板在容器内监听的端口。
ANTHROPIC_API_KEY	(none)	用于 Query 聊天的 Anthropic API 密钥。
SSH_KEY_PATH	(none)	用于主机监控的私钥路径（容器内）。容器用户必须具有读取权限。
SSH_KEY_PASSPHRASE	(none)	如果私钥受密码短语保护，则填写该密码短语。
DISCORD_WEBHOOK_URL	(none)	用于发送任务完成和任务暂停通知的 Discord webhook。
JOB_RUNNER_INTERVAL_SECONDS	60	任务运行器每隔多久推进已启动的任务一部电影（最小值为 10；0 会关闭运行器）。

只读和非 root 运行

从 1.3.0 版开始，容器以非 root 用户 UID 和 GID 65532（distroless 的 nonroot）运行；更早版本以 root 身份运行。镜像不包含 shell 或软件包管理器，且只会写入数据目录，因此也可以在只读文件系统且不授予任何权限的情况下运行：

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

也可通过 CLI 设置：--read-only --cap-drop ALL --security-opt no-new-privileges:true。

命名卷可直接使用：Docker 会将新卷的所有者设置为镜像中 /app/data 的所有者。主机文件夹必须先归 UID 65532 所有：sudo chown -R 65532:65532 /path/to/plex-director/data。若要改用其他用户运行（例如已拥有该文件夹的用户），请添加 user: "1000:1000"（或 --user 1000:1000）。如果数据目录不可写，容器会在启动时停止并打印需要运行的 chown 命令。从 1.2.x 或更早版本升级时，数据目录的所有者为 root；请参阅升级说明。如果使用 SSH 主机监控，挂载的密钥也必须可供容器用户读取。

更新

设置和任务历史记录都保存在数据卷中，因此更新时只需替换容器。

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

验证下载。 每个已发布的镜像都使用 GitHub 的 OIDC 身份通过 cosign 签名（无需管理密钥）：

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

本地构建

git clone https://github.com/HoneyBearTech/plex-director-mcp.git
cd plex-director-mcp
docker build -t plex-director-mcp .

.dockerignore 会将 .env、本地数据库和其他机密排除在构建上下文之外。切勿将机密打包进镜像；请在运行时传入。

不使用 Docker 运行（Claude Desktop）

需要 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 ..

在仓库根目录创建一个 .env 文件，填入你使用的服务（全部可选；你也可以稍后在「设置」页面填写服务详情）：

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

每项配置的作用请参阅参考。以下两种情况很容易出错：

• 注释要单独放在一行，不能跟在值后面（在某些工具中，KEY=abc # note 会让注释成为值的一部分）。
• 路径中有空格时，需要用引号括住整个值： SSH_KEY_PATH="/Users/me/.ssh/my key"，而不是 /Users/me/.ssh/'my key'。

将服务端添加到 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" }
    }
  }
}

将路径替换为实际路径，然后重启 Claude Desktop。服务端会在同一进程中，在 WEB_PORT 上启动 Web 控制面板。

Web 控制面板

控制面板与 MCP 服务运行在同一进程中，使用 WEB_PORT（默认为 3000）。

页面	显示内容
查询	一个聊天框，可使用 Claude 和你的服务回答有关媒体库的问题。搜索结果以带海报的表格形式显示（节目会显示季、集和观看进度），默认显示前 50 条，并提供展开按钮。后续问题会保留上下文；新建聊天会重新开始。需要 ANTHROPIC_API_KEY。
服务端状态	Plex 实时流媒体播放情况和观看统计（来自 Tautulli）。
节点利用率	每个 SSH 主机的 CPU、内存、磁盘、运行时间和容器健康状态。无法访问的主机会显示原因；SSH 密钥已更改的主机会显示标记，并提供信任新密钥按钮（参见安全性）。
队列	SABnzbd 和 qBittorrent 下载队列。
索引器	每个 Prowlarr 索引器的状态（运行正常、近期失败、退避中、已禁用），以及 Prowlarr 自身的健康警告。
任务	批量任务及其进度。此处为只读：请通过 Claude 启动、暂停和取消任务。
设置	每项服务的连接详情。密钥不会发回浏览器，只会显示是否已设置。

设置 WEB_PASSWORD 即可要求登录：用户先看到登录页面，随后获得一个签名的 7 天会话 Cookie（通过 HTTPS 提供服务时会自动标记为 Secure）。失败的登录尝试会受到速率限制。退出登录只会清除浏览器中的 Cookie；若要撤销所有会话，请更改密码。

健康检查接口为 GET /healthz，返回 {"ok":true}，无需登录。Docker 镜像每 30 秒使用 Node 自行执行一次健康检查（镜像中没有 curl），检查端口为所设置的 WEB_PORT。

MCP 工具

Claude Desktop 可使用 26 个工具。标有 ★ 的 12 个工具也供控制面板的「查询」聊天使用。

服务端还会向 MCP 客户端发送简短的使用说明：哪些工具用于回答哪类问题，以及在执行任何会更改服务状态的操作前必须先确认。这些指引也包含在供加载技能的 Agent 使用的 Agent 技能（例如 Claude Code）以及「查询」聊天的提示词中。指引只在 src/guidance.ts 中编写一次。

你的媒体库

工具	功能
★ search_plex_library	按类型、演员、片名、年份和/或媒体库（例如 4k）搜索 Plex 媒体库中的电影和电视节目；可搜索所有媒体库，也可仅搜索电影或电视节目。电视节目会显示季、集和观看进度。可按观看状态（未观看、观看中、已观看）或“过去 N 年未观看”（从添加该片名时开始计算从未观看的情况）筛选，并按最近添加或最近观看排序。可按电视网或制片公司、内容分级（TV-MA、R……）、观众评分、发行年份（某个十年）或“过去 N 天内添加”进一步筛选。观看状态对应应用连接的 Plex 账户。大量结果会分页显示。
★ search_episodes	查找单集电视节目，例如“《明星伙伴》中那集……”，按标题搜索单集、搜索某个日期范围内播出的剧集，或搜索某部剧的季首集或季终集。指定剧名时，会搜索单集标题和剧情简介；不指定剧名时，只搜索标题和播出日期，因为 Plex 无法跨整个媒体库搜索剧情简介。会显示季和集数、播出日期及观看状态。
★ get_on_deck	从 Plex 的 On Deck（继续观看）中回答“接下来该看什么？”，列出看了一部分的电影，以及每部追更剧集的下一集（或正在观看的那一集），按最近活动时间倒序排列，并显示每项的观看进度。以 HD 和 4K 格式保存的同一部电影只显示一项。可仅显示电影或电视节目，也可限定某个媒体库，例如 kids。Plex 最多报告 50 项；观看状态对应应用连接的 Plex 账户。
★ resolve_actor_filmography	列出演员在 TMDb 上的影视作品，可包含电影和电视节目，也可只显示其中一种；每个片名都会标记是否存在于 Plex 中。可按年份范围、是否已拥有及媒体库筛选。通过 TMDb ID 将作品与 Plex 匹配，因此 Plex 中没有 TMDb 匹配项的剧集不会被识别为已拥有。
★ check_series_completeness	回答“这部剧的每一集我都有吗？”。根据 Sonarr 的剧集列表，显示已播出的剧集中有多少已下载、缺少哪些季和集、哪些尚未播出，以及 Sonarr 是否正在监控该剧（以便获取剩余剧集）。直接统计剧集，而非 Sonarr 的统计数据；后者会将只下载了一部分且未受监控的剧集视为完整。不会检查 Plex 扫描到的内容。
★ find_series_gaps	列出缺少已播出剧集的电视节目，缺失最多的排在前面，并显示已下载的数量以及 Sonarr 是否正在寻找剩余剧集。可按是否受监控、是否未受监控或是否正在积极搜索筛选；可按缺失数量筛选（适用于“即将完整”的剧集），也可隐藏没有任何已下载剧集的节目。
★ find_series_by_quality	按 Sonarr 下载的视频画质查找电视节目：例如“我有哪些剧只有 720p？”、“哪些剧有 1080p 或更高画质？”、“哪些剧混有不同画质？”（可作为升级候选）。按最佳画质中的最低画质优先显示，并列出各分辨率对应的文件数。它只能查看 Sonarr 下载的内容，因此不会统计单独 Plex 4K 媒体库中的 4K 副本（请使用 Plex 搜索并选择 4k 媒体库）。只读。
★ check_series_status	查看 Sonarr 对某部剧的记录：是否受监控、画质配置文件和存储位置、下一集的播出时间、上次下载内容的时间、下载队列中的内容，以及已播出的剧集中有多少已下载。
★ diagnose_missing_episodes	根据 Sonarr 的历史记录和下载队列，诊断某部剧已播出但没有文件的集数为何缺失：从未抓取、已抓取但从未导入、下载失败（并显示 Sonarr 给出的原因）、文件已被移除、卡在队列中，或未受监控，因此 Sonarr 从未查找过。可限定某一季或单集。只读。
★ get_upcoming_episodes	根据 Sonarr 日历查看即将播出的电视节目。不指定片名时，可回答“本周有什么剧？”：按日期列出 Sonarr 监控的剧集在未来几天内播出的每一集（默认 7 天，最多 60 天），标记季首集和季终集，并标出已下载的剧集。指定片名时，可回答“这部剧什么时候回归？”，显示其接下来的剧集；如果尚未安排播出或已完结，也会说明。除非特别要求，否则不会显示 Sonarr 未监控的节目，并会报告这类节目的数量。
★ check_movie_status	检查 Radarr 中是否有某部电影，以及其监控状态，并显示图片。
★ diagnose_missing_media	追踪电影在 Radarr 元数据、历史记录和下载队列中的状态，以查明其缺失原因。
search_and_select_movies	搜索 TMDb，并以带编号的网格显示匹配结果。
confirm_selected_choices	将网格中选定编号对应的电影添加到 Radarr 并设为受监控，然后开始搜索下载。会报告已存在的电影，不会重复添加。使用指定的画质配置文件；若未指定，则使用 Settings 页面的 Radarr 选项卡中设置的默认配置文件；若那里也未设置，则使用 Radarr 的第一个配置文件。默认使用 Radarr 的第一个根文件夹，除非另行指定。
下载和索引器

工具	功能
manage_stalled_downloads	AUDIT 会列出停滞或速度缓慢的 qBittorrent 下载及其哈希值；PURGE_STALLED 会根据你指定的哈希值删除对应下载及其文件，不会删除其他内容。
check_indexer_health	报告故障、退避和已禁用的 Prowlarr 索引器，以及 Prowlarr 自身的警告。

后台任务

工具	功能
plan_media_upgrade	找出没有文件或分辨率低于 1080p 的电影，并将其安排为批量任务（仅限电影，默认每批最多 25 部）。
get_background_jobs	列出任务及其进度。
update_job_status	对任务执行 PAUSE、RESUME 或 CANCEL。恢复任务后，任务才会开始运行。
execute_next_job_step	手动搜索任务中的下一部电影。已启动的任务也会由任务运行器自动推进，每分钟搜索一部电影。

基础设施和分析

工具	功能
get_cluster_infrastructure_health	查看每台 SSH 主机的 CPU、内存和 Docker 容器健康状况。
get_cluster_hardware_analytics	以表格形式查看每台主机的 CPU 和内存使用情况。
trust_new_host_key	重建受监控主机后，忘记其已记住的 SSH 密钥，以便下次检查时信任主机当前提供的密钥。仅当设置了 WEB_PASSWORD 时，仪表板上的 信任新密钥 按钮才会执行相同操作。
run_cluster_backup	请求 Radarr、Sonarr 和 Prowlarr（已配置的应用）运行各自内置的数据库备份，等待每项备份完成（最长约一分钟；较慢的备份会报告为仍在运行），并确认有新的备份文件生成，同时报告文件名、大小和时间。备份保留在各应用自己的备份文件夹中；不会复制任何内容。
get_plex_activity	通过 Tautulli 查看实时播放流和转码负载。
get_library_analytics	通过 Tautulli 查看最常观看的标题、热门用户、平台和媒体库。

批量任务的工作方式。 plan_media_upgrade 会创建一个处于 PENDING 状态的任务；在你执行 RESUME 之前，不会运行任何操作。任务启动后，任务运行器会逐步推进，每个间隔（默认 60 秒）执行一次 Radarr 搜索，因此大型批次不会让索引器不堪重负。已暂停、已取消或待处理的任务不会被处理；如果任务连续失败三次（例如 Radarr 已停止运行），则会暂停该任务并向 Discord 报告。

安全

• 在可信网络上运行。 它面向家庭局域网设计，未设计或测试用于暴露到公共互联网。如果确实需要从外部访问，请将其置于你信任的 HTTPS 和反向代理之后。请参阅 SECURITY.md 报告漏洞。
• 设置 WEB_PASSWORD。 如果不设置，任何能够访问该端口的人都可以使用控制面板并更改其设置。
• 密钥仅保留在服务端。 设置页面绝不会返回已保存的密钥或令牌；Plex 艺术图通过服务端代理获取，因此 Plex 令牌不会传到浏览器。
• SSH 主机监控使用密钥认证，并会在首次使用时记住每台主机的密钥。 主机首次连接时，其密钥指纹会被保存；此后，如果密钥不同，连接会在发送任何命令之前被拒绝，且节点利用率页面会将该主机显示为离线，并提供 信任新密钥 按钮，供你在确实重建了主机时使用（该按钮需要 WEB_PASSWORD；如果未设置，请让 Claude Desktop 使用 trust_new_host_key）。如果未设置密码，你网络中的任何人都可能使用该按钮信任冒名顶替者，因此只有设置密码后才会提供该按钮。这可以防止首次联系后主机被替换成冒名顶替者；因此，如果你想确认首次连接的安全性，请将指纹与 ssh-keyscan -t ed25519 <host> | ssh-keygen -lf - 的结果进行比较。请使用专用的非特权用户，并将其置于你信任的网络中。
• 有些工具会更改内容。 confirm_selected_choices 会添加电影并开始下载；manage_stalled_downloads 配合 PURGE_STALLED 使用时，会删除你在 AUDIT 后同意删除的种子及其文件；作业运行器会触发搜索。Claude Desktop 使用工具前会征求你的许可，因此请检查它提出的操作。
• 镜像以非 root 用户（UID 65532）运行；请参阅只读和非 root 运行，进一步限制其权限。

开发

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

控制面板是 web/ 中一个独立的 npm 项目（使用 React、Vite 和 TypeScript，拥有自己的 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

测试使用 Node 内置的测试运行器，无需安装其他内容。测试使用临时数据库运行，绝不会读取你的真实 .env；服务凭据会从环境中移除，且除非测试安装了模拟对象，否则所有 HTTP 请求都会失败，因此运行测试不会触及你的真实服务。test/isolation.test.ts 会在上述任一隔离措施失效时令测试运行失败。

运行时说明

• 状态（设置、作业历史记录、登录密钥）存储在 SQLite 数据库 data/plex_director.db 中；在容器中则位于 /app/data。
• 使用官方 MCP SDK。
• Query 聊天会使用上述工具调用 Anthropic API；除此之外，除 TMDb 的调用以及（如果你进行了设置）Discord 的调用外，没有任何内容会离开你的网络。

CI/CD

.github/workflows/ci.yml 包含三个作业：

• 类型检查与审计（check）在每次向 main 推送以及每次针对 main 的拉取请求时运行：TypeScript 类型检查、测试套件、npm audit --audit-level=high，以及对 web/ 中的仪表盘执行相同的类型检查和审计。
• 构建、冒烟测试与发布（publish）在每次向 main 推送、每次推送 v*.*.* 标签以及每次拉取请求时运行，并且仅在 check 通过后运行。每次运行都会构建镜像，并使用虚拟配置启动镜像以确认其正常运行。推送后会发布到两个镜像仓库（分支推送会标记为 latest 和提交 SHA；标签推送还会使用版本号，例如 1.2.3 和 1.2），运行 Docker Scout 漏洞扫描（结果会显示在作业摘要中，目前不会阻止发布），并使用 cosign 对两个镜像进行签名。
• 创建 GitHub Release（release）仅在推送 v*.*.* 标签后运行，并在 publish 成功后创建带有自动生成说明的 Release。

此外，CodeQL 会在每次推送、每次拉取请求以及每周分析 TypeScript；OpenSSF Scorecard 每周评估仓库的供应链实践（见上方徽章）；Dependabot 每周为 npm、Docker 基础镜像和 GitHub Actions 更新创建拉取请求，除非更新涉及主要版本，否则 CI 通过后会自动合并。

许可证

MIT