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.

Related MCP server: ytm-mcp

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:

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:

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

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.