# music-assistant-mcp-plus

A comprehensive [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for
[Music Assistant](https://music-assistant.io) — 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

```bash
# 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

```jsonc
{
  "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](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`](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`](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](CONTRIBUTING.md)** for dev setup and how to verify commands against your server.

## License

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