plex-mcp

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

Configuration

Two environment variables, both required:

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

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 currently has no auth. 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.

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 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, optionally HOST_PORT.
5. Deploy. Healthcheck reaches green within ~10 seconds.

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