music-assistant-mcp 0.1.0

MCP server for Music Assistant – control playback, browse libraries, and manage queues via AI assistants

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.

Installation

pip install music-assistant-mcp

Or run directly with uvx:

uvx music-assistant-mcp

Configuration

Set environment variables before running:

Variable	Required	Description
MA_SERVER_URL	Yes (or MA_HOST)	Full URL like http://192.168.1.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

Running

music-assistant-mcp
# or
python -m music_assistant_mcp

Generating a Long-Lived Access Token

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.

Claude Code Integration

Add via CLI:

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 to your Claude Code MCP config:

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

Tools (27)

Search & Browse

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

Library

• get_library_artists/albums/tracks/playlists - Browse library with search/filter/pagination
• get_album_tracks - Get tracks on an album
• get_artist_albums - Get albums by an artist
• get_recently_played - Recently played items

Playback

• get_players - List all players and state
• player_play_pause/stop/next/previous - Transport controls
• player_volume - Set volume (0-100)
• player_power - Power on/off
• player_seek - Seek to position

Queue

• play_media - Play URIs on a queue
• get_queue - Queue state
• get_queue_items - Items in queue
• queue_clear - Clear queue
• queue_shuffle - Toggle shuffle
• queue_repeat - Set repeat mode

Playlists

• create_playlist - Create new playlist
• add_playlist_tracks - Add tracks by URI
• remove_playlist_tracks - Remove tracks by position

Resources

• ma://players - All players with current state
• ma://library/stats - Library counts