music-assistant-mcp-plus

A comprehensive Model Context Protocol (MCP) server forMusic Assistant — so any MCP-capable AI (Claude Desktop, Claude Code,etc.) can control your music and manage your Music Assistant setup in plain language.

Why "plus"? The existing community MCP servers cover playback, queues, and search only.music-assistant-mcp-plus adds the parts nobody else does: user & access management,providers/sources, and server/player configuration — a superset, not a duplicate.

Highlights

👥 User & access management — create/enable/disable/delete users, set roles(admin/user/guest), and restrict each user to specific speakers (player_filter)and music sources (provider_filter). Great for giving kids/family music access withoutHome Assistant access.
🔊 Players & playback — list players, play/pause/volume, group/ungroup, transfer, play media.
🎵 Library — search across providers, now-playing, library sync.
🧩 Providers — list configured sources; (admin) remove providers.
🧠 Smart tools — ma_add_family_user (create + restrict in one call), ma_whats_playing.
🛟 Safety-first — read-only mode, and destructive/admin tools gated behind an explicit opt-in.
🔧 ma_raw escape hatch — call any MA API command directly (opt-in) for power users.

Install

# with uv (recommended)
uv tool install music-assistant-mcp-plus
# or from source
git clone https://github.com/chair15/music-assistant-mcp-plus && cd music-assistant-mcp-plus
uv pip install -e .        # or: pip install -e .

Configure

The server talks to the Music Assistant server (the add-on / container), default port 8095— not the Home Assistant UI. Configure via environment variables:

Var	Required	Default	Purpose
`MA_URL`	yes	`http://localhost:8095`	Base URL of the MA server
`MA_TOKEN`	one of these	–	Long-lived token (MA → your profile → Access tokens)
`MA_USERNAME` / `MA_PASSWORD`	one of these	–	Builtin login used if no token
`MA_AUTH_PROVIDER`	no	`builtin`	Auth provider (`builtin` or `homeassistant`)
`MA_READ_ONLY`	no	`false`	Expose only read tools
`MA_ENABLE_ADMIN`	no	`false`	Expose destructive tools (delete user, remove provider)
`MA_ENABLE_RAW`	no	`false`	Expose the `ma_raw` command escape hatch
`MA_TIMEOUT`	no	`15`	HTTP timeout (seconds)

Copy .env.example to .env for reference.

Getting a token

Auth is a bearer token. In Music Assistant → your profile → Access tokens → Add token, nameit (e.g. mcp), and put the value in MA_TOKEN (inside your MCP client's env block). The servernever writes the token to disk — it only reads it from the environment and sends it asAuthorization: Bearer …. Treat it like a password: keep it out of git, and revoke it on thatsame screen if it leaks. Prefer a token over MA_USERNAME/MA_PASSWORD.

Claude Desktop / Claude Code

{
  "mcpServers": {
    "music-assistant-plus": {
      "command": "music-assistant-mcp-plus",
      "env": {
        "MA_URL": "http://homeassistant.local:8095",
        "MA_TOKEN": "your-long-lived-token",
        "MA_ENABLE_ADMIN": "false"
      }
    }
  }
}

(For source checkouts use "command": "uv", "args": ["run", "music-assistant-mcp-plus"].)

Usage & examples

Once connected you drive it in plain language — the AI picks the tool:

You say	Tool(s)
"Who can use Music Assistant?"	`ma_list_users`
"What's playing right now?"	`ma_whats_playing`
"Play some Fleetwood Mac in the living room"	`ma_search` → `ma_play_media`
"Add a user `kids` limited to the playroom Sonos and only the local library"	`ma_add_family_user`
"Restrict a user to just the kitchen speaker"	`ma_set_user_players`
"Disable a user's account"	`ma_disable_user`

Read-only mode (MA_READ_ONLY=true) registers only the read tools — the write tools aren'teven loaded, so the assistant physically can't change anything. Great for a shared/kid-facingassistant. See docs/USAGE.md for token setup, read-only/admin config profiles,.env examples, and more interactions; a ready-to-edit client config is inexamples/claude_desktop_config.json.

Tools

Group	Tools
Read	`ma_server_info`, `ma_list_players`, `ma_now_playing`, `ma_search`, `ma_list_users`, `ma_get_user`, `ma_list_providers`
Players/playback	`ma_player_command`, `ma_set_volume`, `ma_play_media`, `ma_group_players`, `ma_ungroup_player`, `ma_sync_library`, `ma_whats_playing`
Users & access	`ma_create_user`, `ma_update_user`, `ma_enable_user`, `ma_disable_user`, `ma_set_user_players`, `ma_set_user_sources`, `ma_list_tokens`, `ma_create_token`, `ma_add_family_user`
Admin (opt-in)	`ma_delete_user`, `ma_revoke_token`, `ma_remove_provider`
Raw (opt-in)	`ma_raw`

See ROADMAP.md for the full planned surface (~70 tools).

Safety model

Default: read + non-destructive write tools.
MA_READ_ONLY=true: only read tools are registered.
MA_ENABLE_ADMIN=true: adds destructive tools.
MA_ENABLE_RAW=true: adds ma_raw.
Nothing runs without auth; the server exits with a clear message if none is configured.

Status

Early scaffold. Confirmed commands (verified against a live MA 2.9.5 server) are marked in thecode and are safe to rely on; others follow MA's documented category/command pattern — if an argdiffers on your MA version, use ma_raw and please open a PR with the fix.

Contributing

Issues and PRs welcome — especially confirming/correcting command args across MA versions, andimplementing the remaining tools from ROADMAP.md. Run ruff check and pytest before submitting.See CONTRIBUTING.md for dev setup and how to verify commands against your server.

music-assistant-mcp-plus