cast-mcp

Standalone HTTP MCP server for playing audiobooks and local TTS on home speakers.

The service exposes both MCP tools for agents and plain HTTP endpoints for physical devices. Audiobooks are read from ./media by default and streamed to speakers through signed session URLs backed by ffmpeg.

Supported speaker providers:

• Google Cast
• Sonos

Speaker IDs are provider-prefixed, for example cast:boys-room-speaker or sonos:kitchen. Existing unprefixed Cast IDs still work as a compatibility fallback.

It also includes fully local TTS for short spoken messages. Docker defaults to Piper with the en_GB-jenny_dioco-medium voice and falls back to espeak-ng if Piper fails.

Local Setup

bun install
cp .env.example .env
mkdir -p media data
bun run start

Docker

cp .env.example .env
mkdir -p media data
docker compose up -d --build

Docker mounts ./media as /media:ro and ./data as /data.

Library Layout

See MEDIA.md for detailed instructions on where to put audiobook files and what formats are supported.

Each folder under ./media is treated as one book:

media/
  the-hobbit/
    metadata.json
    001.mp3
    002.mp3

Optional metadata.json:

{
  "id": "the-hobbit",
  "title": "The Hobbit",
  "author": "J.R.R. Tolkien"
}

Supported input extensions are currently .mp3, .m4a, .m4b, .aac, .wav, .flac, and .ogg. Streams are transcoded to MP3.

Endpoints

• GET /health
• POST /mcp
• GET /books
• POST /scan
• GET /speakers
• POST /play
• POST /say
• POST /stop
• GET /status/:speakerId
• GET /media/stream.mp3?sessionId=...&sig=...
• GET /tts/:id/audio.mp3?sig=...

Control endpoints require Authorization: Bearer <CONTROL_AUTH_TOKEN> when configured. MCP uses MCP_AUTH_TOKEN.

OpenCode MCP Config

{
  "mcp": {
    "cast-audio": {
      "type": "remote",
      "url": "http://127.0.0.1:4130/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:CAST_MCP_TOKEN}"
      }
    }
  }
}