多房间音乐控制MCP服务

Music Assistant MCP Server

An MCP (Model Context Protocol) server for controlling Music Assistant - manage multi-room audio, playback queues, and search across music providers.

Prerequisites

• A running Music Assistant server
• A long-lived access token (Settings > Users > Long-lived access token)
• uv installed

Installation

No local installation required. Configure your MCP client to run directly from GitHub using uvx:

{
  "mcpServers": {
    "music-assistant": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/davidpadbury/music-assistant-mcp",
        "music-assistant-mcp"
      ],
      "env": {
        "MUSIC_ASSISTANT_URL": "http://your-server:8095",
        "MUSIC_ASSISTANT_TOKEN": "your_token_here"
      }
    }
  }
}

Add this configuration to:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
• Claude Code: ~/.claude.json
• Cursor: Settings > MCP

Running over HTTP (modern MCP protocol)

By default the server speaks stdio, which is limited to MCP protocol version 2025-11-25. To serve over streamable HTTP — required by proxies and clients that only support the 2026-07-28 protocol — run with:

{
  "command": "uvx",
  "args": ["--from", "git+https://github.com/davidpadbury/music-assistant-mcp", "music-assistant-mcp"],
  "env": {
    "MUSIC_ASSISTANT_URL": "http://your-server:8095",
    "MUSIC_ASSISTANT_TOKEN": "your_token_here",
    "MCP_TRANSPORT": "streamable-http",
    "MCP_HOST": "127.0.0.1",
    "MCP_PORT": "8844"
  }
}

Run this as a standalone process (shell, systemd, or your container runtime) — unlike the stdio config above, it is not spawned per-request by a client — and point a streamable-http client or proxy at the endpoint http://127.0.0.1:8844/mcp. Keep MCP_HOST at 127.0.0.1 unless you are deliberately exposing it on your network.

Running with Docker

Prebuilt images are published to GitHub Container Registry: ghcr.io/davidpadbury/music-assistant-mcp (tags latest and sha-<commit>).

docker run -d --name music-assistant-mcp -p 8844:8844 \
  -e MUSIC_ASSISTANT_URL=http://your-server:8095 \
  -e MUSIC_ASSISTANT_TOKEN=your_token_here \
  ghcr.io/davidpadbury/music-assistant-mcp

The image serves streamable HTTP on port 8844 over the modern MCP protocol (http://127.0.0.1:8844/mcp). Set MCP_TRANSPORT=stdio to run it in stdio mode instead. The token is read from the MUSIC_ASSISTANT_TOKEN environment variable at runtime — it is never baked into the image.

Compose equivalent:

services:
  music-assistant-mcp:
    image: ghcr.io/davidpadbury/music-assistant-mcp:latest
    ports:
      - "8844:8844"
    environment:
      MUSIC_ASSISTANT_URL: http://your-server:8095
      MUSIC_ASSISTANT_TOKEN: your_token_here
    restart: unless-stopped

Quick Start

1. List available speakers: Use ma_list_players to see all speakers and their current state
2. Search for music: Use ma_search with a query to find songs, albums, artists, or playlists
3. Play music: Use ma_play_media with the URI from search results and a player ID
4. Control playback: Use ma_playback to play, pause, skip, or seek

Available Tools

Player Tools

Playback Tools

Queue Tools

Music Library Tools

Common Workflows

Play Music on a Speaker

1. ma_list_players()                           → Get player IDs
2. ma_search(query="Beatles Abbey Road")       → Find the album, get URI
3. ma_play_media(queue_id="living_room", media="spotify://album/xxx")

Group Speakers for Multi-Room Audio

1. ma_list_players()                           → See available speakers
2. ma_group(action="join", player_ids=["kitchen", "bedroom"], target_player_id="living_room")
3. Now all three speakers play in sync

Add to the Current Queue

1. ma_search(query="Bohemian Rhapsody", media_types=["track"])
2. ma_play_media(queue_id="living_room", media="spotify://track/xxx", option="add")

Control What's Playing

- Pause: ma_playback(queue_id="living_room", command="pause")
- Skip: ma_playback(queue_id="living_room", command="next")
- Volume: ma_volume(player_id="living_room", level=50)

Transfer Playback to Another Room

ma_transfer_queue(source_queue_id="living_room", target_queue_id="kitchen")
→ Music moves to kitchen, continuing from the same position

Understanding IDs

• player_id: Identifies a speaker (e.g., "living_room"). Get from ma_list_players
• queue_id: Usually the same as player_id. Each player has its own queue
• item_id: Identifies a track in a queue. Get from ma_queue
• URI: Identifies a media item (e.g., "spotify://track/abc123"). Get from ma_search or ma_browse

Tips

• Always call ma_list_players first to discover available speakers and their IDs
• Use ma_search to find media before trying to play it
• When grouping speakers, the target_player_id becomes the group leader
• Queue IDs are typically the same as player IDs
• Use option="add" with ma_play_media to add to queue without interrupting current playback

License

MIT