music-assistant-mcp-plus

A comprehensive Model Context Protocol (MCP) server for Music 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 without Home 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, name it (e.g. mcp), and put the value in MA_TOKEN (inside your MCP client's env block). The server never writes the token to disk — it only reads it from the environment and sends it as Authorization: Bearer …. Treat it like a password: keep it out of git, and revoke it on that same 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't even loaded, so the assistant physically can't change anything. Great for a shared/kid-facing assistant. See docs/USAGE.md for token setup, read-only/admin config profiles, .env examples, and more interactions; a ready-to-edit client config is in examples/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 the code and are safe to rely on; others follow MA's documented category/command pattern — if an arg differs 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, and implementing 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.

License

MIT © chair15. Not affiliated with the Music Assistant project.