music-assistant-mcp

An MCP server that wraps the Music Assistant client library, exposing music search, library browsing, playback control, queue management, and playlist curation to AI assistants.

Configuring and Installing

Generate a Long-Lived Access Token First

1. Navigate to your Music Assistant instance at http://<your-ma-host>:8095/#/settings/profile.
2. Scroll down to the Long-lived access token section and click + Create new token.
3. Assign a name and submit.
4. Copy the generated token value to a safe place — you will need it in the setup steps below.

Get Environment Variables Ready

To reach a Music Assistant instance, you'll need to set some environment variables:

Variable	Required	Description
MA_SERVER_URL	Yes (or MA_HOST)	Full URL like http://10.10.10.10:8095
MA_HOST	No	Hostname, combined with MA_PORT
MA_PORT	No	Defaults to 8095
MA_TOKEN	Yes	Bearer token generated by Music Assistant

You don't necessarily have to set these in your shell in a persistent way. These variables can typically be injected into the MCP server's execution context as necessary as shown in the examples below.

Claude Integration

Many will want to use this MCP server from Claude Desktop, Claude Code, or another MCP host. You can add the MCP server to Claude Code with the CLI like this:

claude mcp add --transport stdio music-assistant \
  --env MA_SERVER_URL=http://your-ma-host:8095 \
  --env MA_TOKEN=your-token \
  -- uvx music-assistant-mcp

Or add it to your Claude Code or Claude Desktop MCP configuration files as follows:

{
  "mcpServers": {
    "music-assistant": {
      "command": "uvx",
      "args": ["music-assistant-mcp@latest"],
      "env": {
        "MA_SERVER_URL": "http://your-ma-host:8095",
        "MA_TOKEN": "your-token"
      }
    }
  }
}

Hosting in a Container

When you run the Music Assistant MCP server in a Docker container, your MCP client can't get to the stdin and stdout file descriptors of the server. You'll have to use the streamable-http transport instead. This MCP server uses three more environment variables to configure for this case:

Variable	Required	Description
MA_MCP_TRANSPORT	No	Transport protocol: stdio (default) or streamable-http
MA_MCP_HOST	No	IP address to bind (default 0.0.0.0)
MA_MCP_PORT	No	Port to listen on (default 8000)

Check out the sample MA_MCP_Docker project that shows how to build a Docker container that uses them to host this server.

A Note on Authentication

The stdio transport is unauthenticated because only the spawning process has access to the server's stdin and stdout file descriptors. With HTTP however, the endpoint becomes network-accessible so you need to take care when running the server in any sort of container.

If this is on your home lab and isolated to a VLAN that you control, you're probably fine. But if you're exposing it more broadly, it is highly recommended that you put the service behind an nginx reverse proxy with bearer token authorization at a minimum.

Tools (19)

The tools exposed by the Music Assistant MCP server generally follow the pattern of the underlying music-assistant module upon which it is built. However, MCP clients often become overwhelmed by having too many choices, so some related functions have been grouped into tools like manage_favorites and player_control with a range of actions available on them.

Search & Browse

• search_music - Search across all providers
• browse_media - Browse provider folders
• get_item_by_name - Find item by name, artist, album

Library & Discovery

• get_library - Browse library by media type (artist, album, track, playlist) with search/filter/pagination
• get_item_children - Get child items: album tracks, artist albums, artist top tracks, or playlist tracks
• get_similar_tracks - Get tracks similar to a given track
• get_recommendations - Get personalized recommendations
• get_recently_played - Recently played items
• get_library_stats - Library counts (tracks, albums, artists, playlists)
• get_server_info - Server version, Music Assistant backend details, and connected providers
• manage_favorites - Add or remove items from favorites

Playback

• get_players - List all players and state
• player_control - Control a player: play, pause, stop, next, previous, seek, volume, mute, power, group, ungroup

Queue

• play_media - Play URIs on a queue
• get_queue - Queue state
• get_queue_items - Items in queue
• queue_control - Queue settings: clear, shuffle, repeat

Playlists

• create_playlist - Create new playlist
• manage_playlist_tracks - Add or remove tracks from a playlist

Resources (2)

As of this writing, Claude Desktop doesn't support MCP resources well. In a future release, that may change. For now, we've also made these resources available as tools as described.

• ma://players - All players with current state (also available as the get_players tool)
• ma://library/stats - Library counts (also available as the get_library_stats tool)