plex-mcp

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

An MCP server for Plex Media Server, packaged as a Docker container. Lets an MCP client (Claude Desktop, etc.) browse and search your Plex libraries.

Tools

Related MCP server: Plex Assistant MCP

Configuration

Two environment variables, both required:

To find your Plex token, see Plex's Finding an authentication token guide.

Optional environment variables

All have working defaults; set only to override.

LOG_LEVEL, MCP_ALLOWED_HOSTS/MCP_ALLOWED_ORIGINS, and HOST_IMAGE_DIR/HOST_LOG_DIR are covered in their own sections below (Logging, HTTP transport hardening, Portainer deploy) since each needs more than a one-line note.

Plex on the same host as the container? Use PLEX_URL=http://host.docker.internal:32400. The compose file maps host.docker.internal to the Docker host gateway via extra_hosts, so the container can reach a Plex server running on the host. The host's own hostname (e.g. my-nas) won't resolve from inside the container without that mapping.

Transport modes

In HTTP mode the server exposes:

• POST/GET/DELETE /mcp — MCP Streamable HTTP endpoint (per spec)

• GET /health — liveness probe (used by docker healthcheck)

HTTP mode has no caller authentication — TLS (below) encrypts traffic but doesn't identify the caller. Bind only to a private network. Rely on host firewall or LAN isolation. Don't expose to the public internet without adding bearer-token auth first.

Enabling HTTPS

HTTPS is opt-in. Resolution order at startup:

1. Bring-your-own cert — set both MCP_TLS_CERT_FILE and MCP_TLS_KEY_FILE to PEM file paths. Use this when terminating Let's Encrypt or an internal CA. The server reads them at startup; restart the container to pick up renewed files.

2. Self-managed cert (recommended for LAN-only setups) — set MCP_TLS=auto. The server generates an ECDSA P-256 self-signed cert on first start, writes it to MCP_TLS_DIR (default /data/certs), and reuses it on subsequent starts. When the cert is within 30 days of expiry it's regenerated automatically.

3. Otherwise the server stays on plain HTTP (today's default).

On startup the server logs the cert's SHA-256 fingerprint and notAfter. Pin the fingerprint client-side, or trust the cert in your OS keystore for browsers and CLI tools.

When TLS is on, the compose healthcheck needs the --no-check-certificate flag — update the test: line to ["CMD", "wget", "--no-check-certificate", "-q", "-O-", "https://localhost:3000/health"].

Pointing mcp-remote at an HTTPS endpoint

For a self-signed cert, either pin the cert file via Node's CA bundle or skip verification on the client (LAN-only):

# 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

Reverse-proxy alternative

In-process TLS is convenient when you don't already run an ingress controller. If you have Caddy, Traefik, or nginx in front of your home services, the more idiomatic pattern is to terminate TLS at the proxy (with automatic Let's Encrypt) and keep plex-mcp on plain HTTP behind it. The two approaches are interchangeable — pick whichever matches your existing setup.

Run with Docker (stdio, on demand)

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

Run with Docker Compose (HTTP, long-lived)

The compose file pulls ghcr.io/carldog/plex-mcp:latest (multi-arch: linux/amd64 + linux/arm64), published by CI on every push to 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

The MCP endpoint will be at http://<host>:${HOST_PORT}/mcp.

To rebuild from source instead of pulling:

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

Deploy via Portainer (Stack from Git)

1. In Portainer, Stacks → Add Stack → Repository.

2. Repository URL: https://github.com/CarlDog/plex-mcp

3. Compose path: docker-compose.yml

4. Environment variables: set PLEX_URL, PLEX_TOKEN, MCP_ALLOWED_HOSTS, HOST_IMAGE_DIR, and HOST_LOG_DIR — all required (see below); optionally HOST_PORT.

5. Deploy. Healthcheck reaches green within ~10 seconds.

MCP_ALLOWED_HOSTS is required in HTTP mode

Comma-separated list of Host header values the server accepts on /mcp — e.g. nas.local:3001 (must match whatever host:port a client actually dials, including the mapped HOST_PORT). The server refuses to start in HTTP mode without it, and docker compose config fails the same way if it's unset — both fail before the container ever comes up, deliberately, rather than starting in a silently-unprotected state.

This exists because binding 0.0.0.0 inside a container isn't a real access boundary the way loopback binding is on a bare host: a page loaded in a browser anywhere on the LAN can perform DNS rebinding — pointing its own hostname at this container's IP — and drive tools (including writes like plex_delete_playlist) as a confused deputy, entirely bypassing "LAN-only, no bearer token" as a security posture. The Host allowlist closes that gap without requiring full authentication. MCP_ALLOWED_ORIGINS (optional, default empty) does the same for the Origin header — leave it unset unless a browser-based client legitimately needs to call this server directly; non-browser clients (the mcp-remote bridge, a direct fetch) never send an Origin header, so the empty default only ever rejects the request shape a DNS-rebinding attack actually sends.

HOST_IMAGE_DIR and HOST_LOG_DIR are required — no relative default

Both volume host paths are ${VAR:?...} in the compose file: there is no fallback default, so docker compose up / a Portainer redeploy fails fast with a clear error if either is unset, rather than starting in a broken state.

This used to be a soft ${VAR:-./data/images} default, which is only safe for a local docker compose up from a stable clone. In a Portainer git stack it's a trap: every redeploy clones the repo into a fresh per-commit directory (/data/compose/<stack-id>/<commit>/), where a relative path like ./data/images doesn't exist. Docker refused the bind mount and the container was left stuck in created state — it never started. That also hit automatic redeploys (image update, git poll), so a previously healthy stack went down with no manual action; the only symptom was the container sitting in created. This took the deployed stack down for ~10 hours on 2026-07-31 — see docker-deployments.md rule #10 and fleet lesson 2026-07-31-relative-compose-volume-defaults-break-portainer-git-stacks. The compose file now makes the requirement structural instead of a documentation-only convention.

Set both to absolute host paths in the stack's environment variables:

• HOST_IMAGE_DIR — the plex_save_image output directory. Recommended: the host directory backing filesystem-mcp's /media/_mcp-scratch mount — e.g. /volume1/Media/_mcp-scratch on a Synology NAS — which keeps the plex_search → plex_save_image → filesystem-mcp pipeline on one shared directory.

• HOST_LOG_DIR — the plex_download_logs output directory, kept separate from HOST_IMAGE_DIR since a diagnostic ZIP isn't a media artifact — e.g. /volume1/docker/plex-mcp/logs on a Synology NAS (matching this fleet's per-container appdata convention).

Make sure both directories exist on the host before the first deploy: Docker does not auto-create a missing bind-mount source, it just refuses to start the container.

Use with Claude Desktop

stdio (local invocation)

{
  "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 (remote MCP server)

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

(Requires Claude Desktop or a client that supports remote MCP HTTP.)

Local development

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

Logging

The server emits structured logs to stderr (stdout is the MCP wire protocol in stdio mode and must not be polluted). Format:

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

Configure verbosity via the LOG_LEVEL env var (default info):

Container logs are captured by Docker's json-file driver and rotated automatically (10MB × 3 files = ~30MB cap; oldest deleted on rotation). View with docker logs plex-mcp or docker logs -f.

Security

• The container runs as a non-root user (plexmcp).

• The Plex token is passed via env var — never bake it into the image.

• A .githooks/pre-commit runs gitleaks on every commit. Activate it once per clone: git config core.hooksPath .githooks