cast-mcp

Standalone HTTP MCP server for casting audiobooks from a filesystem library to Google Cast 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.

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

Related MCP server: sonos-mcp

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?sessionId=...&sig=...

• GET /tts/:id?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}"
      }
    }
  }
}