IPTV管理MCP服务器

dispatcharr-mcp

An MCP server for Dispatcharr — giving AI agents full control over your IPTV streams, channels, EPG, and VOD library.

Authentication

Two modes are supported — DISPATCHARR_API_KEY takes priority if set:

If DISPATCHARR_API_KEY is set, the username/password are ignored — a rejected key is reported as an error (with Dispatcharr's reason, e.g. Invalid API key) rather than falling back to a login. An empty DISPATCHARR_API_KEY counts as unset.

To generate an API key: Dispatcharr UI → System → Users → edit your user → copy the API Key field.

The key is sent as Authorization: ApiKey <key>. Dispatcharr also accepts X-API-Key: <key>, but not Api-Key — that scheme is silently ignored, so it appears to work against public endpoints such as /api/core/version/ while every protected one returns 401. If calls fail with 401 in API key mode, the key itself is wrong or has been regenerated; update DISPATCHARR_API_KEY rather than the header.

Tools

TODO

The following API endpoints are not yet implemented. Contributions welcome.

Tier 2 — Useful management operations

• File uploads — upload_backup, upload_channel_logo (multipart file upload, requires different client support)

Tier 3 — Niche / lower priority

• Plugin extras — refresh_plugin_repo, install_plugin, list_available_plugins, get_repo_settings, update_repo_settings, preview_plugin, get_plugin_detail (not present in current swagger spec)

Setup

There are two ways to run dispatcharr-mcp. Choose the one that fits your setup:

Where do these config snippets go?

All the snippets below are MCP server configuration. Where you put them depends on your AI client:

Tip: Use a project-scoped .mcp.json when you want to commit the config with your project. Use user/global config when you want dispatcharr-mcp available everywhere.

Docker

Pre-built images are published to the GitHub Container Registry for linux/amd64 and linux/arm64.

The Docker image runs in streamable-http mode, exposing the MCP server on port 8000. Your AI client connects over HTTP — credentials stay in the container, not in your IDE config.

Start the container

docker run -d -p 8000:8000 \
  -e DISPATCHARR_URL=http://your-dispatcharr-host:9191 \
  -e DISPATCHARR_API_KEY=your-api-key \
  -e FASTMCP_HOST=0.0.0.0 \
  ghcr.io/crunchingcode/dispatcharr-mcp:latest

Connect your AI client (HTTP)

Add one of these to your .mcp.json (project root) or your client's global config — see the table above for file locations.

Same machine as the container:

{
  "servers": {
    "dispatcharr": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Container on a different machine on your LAN:

{
  "servers": {
    "dispatcharr": {
      "type": "http",
      "url": "http://192.168.1.x:8000/mcp"
    }
  }
}

Local Installation

Use this approach when you want the MCP server to run as a subprocess on the same machine as your IDE.

Requirements

• Python 3.10+
• A running Dispatcharr instance (v0.20+)
• A Dispatcharr API key or a username + password

Install

git clone https://github.com/crunchingcode/dispatcharr-mcp
cd dispatcharr-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

Connect your AI client (stdio)

Add one of these to your .mcp.json (project root), VS Code user settings, or Claude Desktop config — see the table above for file locations.

API Key (recommended):

{
  "servers": {
    "dispatcharr": {
      "type": "stdio",
      "command": "/path/to/dispatcharr-mcp/.venv/bin/dispatcharr-mcp",
      "args": [],
      "env": {
        "DISPATCHARR_URL": "http://your-dispatcharr-host:9191",
        "DISPATCHARR_API_KEY": "your-api-key"
      }
    }
  }
}

Username/Password (JWT):

{
  "servers": {
    "dispatcharr": {
      "type": "stdio",
      "command": "/path/to/dispatcharr-mcp/.venv/bin/dispatcharr-mcp",
      "args": [],
      "env": {
        "DISPATCHARR_URL": "http://your-dispatcharr-host:9191",
        "DISPATCHARR_USERNAME": "mcp",
        "DISPATCHARR_PASSWORD": "your-password"
      }
    }
  }
}

CLI / manual

export DISPATCHARR_URL=http://dispatcharr.local:9191
export DISPATCHARR_API_KEY=your-api-key   # or use USERNAME + PASSWORD below

.venv/bin/dispatcharr-mcp

Environment Variables

Credential masking

Tool results never show provider credentials or API keys by default. Instead, <redacted> takes their place in:

• URLs: user:pass@, ?username=…&password=…, and Xtream Codes paths such as /live/<user>/<pass>/123.ts, anywhere in a result, including log files and error messages
• values under keys such as password, token, secret and authorization
• API keys, which keep their last four characters (<redacted>a1b2) so you can tell them apart

generate_api_key, get_backup_download_token and create_catchup_session exist to return a credential, so their results are not masked. A tool call whose arguments contain <redacted> is refused, so a masked URL can't be written back over the real one. Only the operator can turn masking off; the model can't.

License

MIT