plex-mcp

· claude-opus-4-8[1m] · 2026-07-07 · 详情

一个面向 Plex Media Server 的 MCP 服务器，打包为 Docker 容器。它让 MCP 客户端（Claude Desktop 等）能够浏览和搜索你的 Plex 媒体库。

工具

Related MCP server: Plex Assistant MCP

配置

两个环境变量，均为必填：

要找到你的 Plex 令牌，请参阅 Plex 的 查找身份验证令牌 指南。

可选环境变量

全部都有可用的默认值；仅需在需要覆盖时设置。

LOG_LEVEL、MCP_ALLOWED_HOSTS/MCP_ALLOWED_ORIGINS 和 HOST_IMAGE_DIR/HOST_LOG_DIR 将在下文各自的章节（日志、HTTP 传输加固、 Portainer 部署）中说明，因为每项都不止需要一行注释。

Plex 与容器在同一主机上？ 使用 PLEX_URL=http://host.docker.internal:32400。compose 文件通过 extra_hosts 将 host.docker.internal 映射到 Docker 主机网关， 因此容器可以访问运行在主机上的 Plex 服务器。如果没有该映射， 容器内部将无法解析主机自身的主机名（例如 my-nas）。

传输模式

在 HTTP 模式下，服务器暴露：

• POST/GET/DELETE /mcp — MCP Streamable HTTP 端点（按规范）

• GET /health — 存活探针（用于 docker healthcheck）

HTTP 模式没有调用方认证——TLS（见下文）对流量加密，但不会识别调用方。 请仅绑定到私有网络。依赖主机防火墙或局域网隔离。在未先添加 bearer-token 认证的情况下，不要暴露到公共互联网。

启用 HTTPS

HTTPS 为可选启用。启动时的解析顺序：

1. 自带证书 — 将 MCP_TLS_CERT_FILE 和 MCP_TLS_KEY_FILE 都设置为 PEM 文件路径。在终止 Let's Encrypt 或内部 CA 时使用此项。服务器在启动时读取这些文件； 重启容器以加载续期后的文件。

2. 自管理证书（推荐用于纯局域网环境）— 设置 MCP_TLS=auto。服务器在首次启动时生成一个 ECDSA P-256 自签名 证书，将其写入 MCP_TLS_DIR（默认 /data/certs），并在后续启动时复用。当证书在到期前 30 天内时，会自动重新生成。

3. 否则服务器保持纯 HTTP（当前默认）。

启动时，服务器会记录证书的 SHA-256 指纹和 notAfter。在客户端固定该指纹，或在操作系统密钥库中信任该 证书，以供浏览器和 CLI 工具使用。

当 TLS 开启时，compose healthcheck 需要 --no-check-certificate 标志——将 test: 行更新为 ["CMD", "wget", "--no-check-certificate", "-q", "-O-", "https://localhost:3000/health"]。

将 mcp-remote 指向 HTTPS 端点

对于自签名证书，要么通过 Node 的 CA 捆绑包固定证书文件， 要么在客户端跳过验证（仅限局域网）：

# Trust the server's self-signed cert (preferred):
NODE_EXTRA_CA_CERTS=./server.crt \
  npx -y mcp-remote https://nas.local:3443/mcp

# Or skip verification for quick testing (LAN-only):
NODE_TLS_REJECT_UNAUTHORIZED=0 \
  npx -y mcp-remote https://nas.local:3443/mcp

反向代理替代方案

当你尚未运行入口控制器时，进程内 TLS 很方便。如果你在 家庭服务前面有 Caddy、Traefik 或 nginx，更惯用的模式是在 代理处终止 TLS（使用自动 Let's Encrypt），并让 plex-mcp 在其后面保持纯 HTTP。这两种方法可以互换——选择 与你现有环境匹配的一种即可。

OAuth 2.1 bearer-token 认证（可选启用，尚不能实际使用）

代码端已具备 OAuth 2.1 受保护资源认证的支持 （ChatGPT Apps SDK 对齐阶段 2——完整计划见 docs/CHATGPT-APPS-SDK.md）， 但尚不是你可以实际开启并使用的东西：它需要一个真实的 OAuth 2.1 身份提供方来签发令牌，而此部署尚未配置这样的提供方 （那是阶段 3，尚未开始）。此处记录仅为完整性，并非操作指南。

启用后，每个 /mcp 请求都需要 Authorization: Bearer <jwt>—— 由已配置的 IdP 签发，并带有正确的受众和范围。/health 始终不受影响（它是独立的路由，而且 Docker 自身的 healthcheck 无法附加 bearer token）。/.well-known/oauth-protected-resource 按 RFC 9728 自动提供服务。

使用 Docker 运行（stdio，按需）

docker build -t plex-mcp .
docker run -i --rm \
  -e PLEX_URL=http://192.168.1.50:32400 \
  -e PLEX_TOKEN=your-token \
  plex-mcp

使用 Docker Compose 运行（HTTP，长期运行）

compose 文件拉取 ghcr.io/carldog/plex-mcp:latest（多架构： linux/amd64 + linux/arm64），由 CI 在每次推送到 main 时发布。

# Required env vars (or use a .env file):
export PLEX_URL=http://192.168.1.50:32400
export PLEX_TOKEN=your-token
export MCP_ALLOWED_HOSTS=nas.local:3001  # required — see below
export HOST_PORT=3001  # optional, defaults to 3001

docker compose up

MCP 端点将位于 http://<host>:${HOST_PORT}/mcp。

要从源码重新构建而不是拉取：

docker build -t ghcr.io/carldog/plex-mcp:latest .
docker compose up

通过 Portainer 部署（来自 Git 的 Stack）

1. 在 Portainer 中，Stacks → Add Stack → Repository。

2. 仓库 URL：https://github.com/CarlDog/plex-mcp

3. Compose 路径：docker-compose.yml

4. 环境变量：设置 PLEX_URL、PLEX_TOKEN、 MCP_ALLOWED_HOSTS、HOST_IMAGE_DIR 和 HOST_LOG_DIR——全部 必填（见下文）；HOST_PORT 可选。

5. 部署。healthcheck 在约 10 秒内变为绿色。

HTTP 模式下必须设置 MCP_ALLOWED_HOSTS

服务器在 /mcp 上接受的 Host 头值的逗号分隔列表—— 例如 nas.local:3001（必须与客户端实际拨打的 host:port 匹配，包括映射后的 HOST_PORT）。没有它， 服务器在 HTTP 模式下拒绝启动；如果未设置，docker compose config 也会以同样的方式失败——两者都在容器启动之前就失败，这是 有意为之，而不是以悄然无保护的状态启动。

这样做的原因是，容器内绑定 0.0.0.0 并不像裸主机上的 回环绑定那样是真正的访问边界：局域网上任意位置浏览器中 加载的页面都可以执行 DNS 重绑定——将自己的主机名指向此 容器的 IP——并作为混乱代理驱动各种工具（包括 plex_delete_playlist 之类的写入操作），从而完全绕过 “仅限局域网、无 bearer token”这一安全姿态。 Host 允许列表在不要求完整认证的情况下弥补了这一缺口。 MCP_ALLOWED_ORIGINS（可选，默认空）对 Origin 头做同样 的事情——除非基于浏览器的客户端确实需要直接调用此服务器， 否则请保持未设置；非浏览器客户端（mcp-remote 桥接、直接的 fetch）从不发送 Origin 头，因此空的默认值只会拒绝 DNS 重绑定攻击实际发送的请求形态。

HOST_IMAGE_DIR 和 HOST_LOG_DIR 为必填——没有相对路径默认值

compose 文件中两个卷的主机路径均为 ${VAR:?...}：没有 回退默认值，因此如果其中任何一个未设置，docker compose up / Portainer 重新部署都会以明确的错误快速失败，而不是在损坏的 状态下启动。

以前这是一个软默认值 ${VAR:-./data/images}，它只对从稳定 克隆进行的本地 docker compose up 是安全的。在 Portainer git stack 中，它是一个陷阱：每次重新部署都会将仓库克隆到 一个全新的按提交划分的目录（/data/compose/<stack-id>/<commit>/）， 而 ./data/images 这样的相对路径在那里并不存在。Docker 拒绝了绑定挂载，容器因此卡在 created 状态——从未启动。 这也影响到了自动重新部署（镜像更新、git 轮询），所以一个 原本健康的 stack 在没有任何手动操作的情况下宕机了；唯一的 症状就是容器停在 created 状态。这导致已部署的 stack 在 2026-07-31 宕机了约 10 小时——参见 docker-deployments.md 规则 #10 和舰队经验教训 2026-07-31-relative-compose-volume-defaults-break-portainer-git-stacks。 compose 文件现在将这一要求变为结构性的，而不仅仅是文档约定。

在 stack 的环境变量中将两者都设置为绝对主机路径：

• HOST_IMAGE_DIR —— plex_save_image 的输出目录。 建议：使用 filesystem-mcp 的 /media/_mcp-scratch 挂载所对应的主机目录——例如 Synology NAS 上的 /volume1/Media/_mcp-scratch——这样 plex_search → plex_save_image → filesystem-mcp 流水线就可以在同一个共享目录中运行。

• HOST_LOG_DIR —— plex_download_logs 的输出目录，与 HOST_IMAGE_DIR 分开存放，因为诊断 ZIP 不是媒体产物——例如 Synology NAS 上的 /volume1/docker/plex-mcp/logs（与本机群按容器隔离 appdata 的惯例保持一致）。

请确保这两个目录在首次部署 之前 就已存在于主机上：Docker 不会自动创建缺失的绑定挂载源，只会拒绝启动容器。

与 Claude Desktop 配合使用

stdio（本地调用）

{
  "mcpServers": {
    "plex": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "PLEX_URL", "-e", "PLEX_TOKEN",
        "plex-mcp"
      ],
      "env": {
        "PLEX_URL": "http://192.168.1.50:32400",
        "PLEX_TOKEN": "your-token"
      }
    }
  }
}

HTTP（远程 MCP 服务器）

{
  "mcpServers": {
    "plex": {
      "url": "http://nas.local:3001/mcp"
    }
  }
}

（需要 Claude Desktop 或支持远程 MCP HTTP 的客户端。）

本地开发

npm install
cp .env.example .env  # then edit
PLEX_URL=... PLEX_TOKEN=... npm run dev               # stdio
MCP_PORT=3000 MCP_ALLOWED_HOSTS=localhost:3000 PLEX_URL=... PLEX_TOKEN=... npm run dev # HTTP

日志

服务器将结构化日志输出到 stderr（在 stdio 模式下，stdout 承载 MCP 线协议，不能被污染）。格式：

2026-04-29T15:30:00.000Z INFO [tool:plex_browse] invoke section_id=7 type=show limit=2
2026-04-29T15:30:00.337Z INFO [tool:plex_browse] ok ms=337

通过 LOG_LEVEL 环境变量配置日志详细程度（默认 info）：

容器日志由 Docker 的 json-file 驱动捕获并自动轮转（10MB × 3 个文件 = ~30MB 上限；轮转时删除最旧的）。使用 docker logs plex-mcp 或 docker logs -f 查看。

安全

• 容器以非 root 用户（plexmcp）身份运行。

• Plex 令牌通过环境变量传入——切勿将其固化到镜像中。

• .githooks/pre-commit 会在每次提交时运行 gitleaks。每次克隆后激活一次：git config core.hooksPath .githooks