podium-mcp

An MCP server for Podium, the provider-aware stream checker and reorderer for Dispatcharr. It lets Claude and other MCP clients inspect Podium's state, run checks, preview and apply stream orderings, and manage rules and settings.

You run it yourself, next to your own Podium instance. Nothing is hosted.

Quick start (Docker)

docker run -d --name podium-mcp \
  -p 127.0.0.1:8080:8080 \
  -e PODIUM_URL=http://<podium-host>:<port> \
  -e MCP_AUTH_TOKEN=change-me \
  ghcr.io/OWNER/podium-mcp:latest

Bind the published port to a specific interface (127.0.0.1 above) unless you intend to expose the server to your LAN, and set MCP_AUTH_TOKEN if you do.

Or copy .env.example to .env, fill it in, and run docker run --env-file .env ... instead of repeating -e flags. Alternatively copy docker-compose.example.yml to docker-compose.yml, edit the values (or add env_file: .env), and run docker compose up -d.

Check it is up: curl http://localhost:8080/healthz returns {"ok":true}.

Related MCP server: Tomo Streaming MCP

Configuration

The image EXPOSEs 8080, so if you change MCP_PORT you must change the container side of the port mapping to match (for example -p 127.0.0.1:9000:9000 with MCP_PORT=9000).

Connecting a client

Claude Code (HTTP)

claude mcp add --transport http podium http://localhost:8080/mcp \
  --header "Authorization: Bearer change-me"

Claude Desktop (HTTP)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "podium": {
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "headers": { "Authorization": "Bearer change-me" }
    }
  }
}

Any client (stdio via Docker)

{
  "mcpServers": {
    "podium": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "PODIUM_URL=http://<podium-host>:<port>",
        "-e", "MCP_TRANSPORT=stdio",
        "ghcr.io/OWNER/podium-mcp:latest"
      ]
    }
  }
}

Tools

Read-only:

Actions:

Opt-in (PODIUM_MCP_ENABLE_DESTRUCTIVE=true):

Every tool carries MCP annotations (readOnlyHint, destructiveHint) so clients that honour them can prompt appropriately.

Safety notes

• podium_apply_ordering and podium_unassign_stream change live Dispatcharr channels through Podium. The confirm: true argument is a guard against accidental calls by a model. It is not a security boundary. Anyone who can reach the /mcp endpoint can call these tools, so set MCP_AUTH_TOKEN and keep the port off the public internet.

• Through the default tool set the server never reads or writes Dispatcharr credentials. Secret settings are masked on read and refused on write.

• The opt-in podium_backup tool (behind PODIUM_MCP_ENABLE_DESTRUCTIVE=true) exports and restores Podium's raw backup document, which can include Podium's stored configuration and secrets. Leave the flag off unless you need it, and treat exported backups as sensitive.

• If MCP_AUTH_TOKEN is unset, the server logs a startup warning that /mcp is unauthenticated. Idle HTTP sessions are closed after 30 minutes.

• Podium rewrites a channel's aliases, contains and exclude lines on every rule save, and resets a group's mode to always when none is sent. That is why podium_rules requires those three lists and podium_set_group requires mode: read the current values with podium_state first. Group name patterns are listed there too, under patterns.

Built against Podium 1.17.0. Older Podium releases ignore the fields they do not know, such as maxResolution, group filters, pruned and excludeFast; before 1.17, per-alias and per-contains group filters keep only excludeGroups.

Development

npm install
npm test
npm run build
PODIUM_URL=http://<podium-host>:<port> npm start

npm run smoke calls every read tool once against the Podium at PODIUM_URL.

Images: every push to master publishes a multi-arch image to GHCR as latest and sha-<commit>. Pushing a tag like v0.1.0 also publishes the 0.1.0 and 0.1 tags and creates a GitHub Release.

Licence

MIT. See LICENSE.