Metadata-Version: 2.4
Name: music-assistant-mcp
Version: 0.2.1
Summary: MCP server for Music Assistant – control playback, browse libraries, and manage queues via AI assistants
Project-URL: Homepage, https://github.com/devjourney/music-assistant-mcp
Project-URL: Repository, https://github.com/devjourney/music-assistant-mcp.git
Project-URL: Bug Tracker, https://github.com/devjourney/music-assistant-mcp/issues
Project-URL: Changelog, https://github.com/devjourney/music-assistant-mcp/blob/main/CHANGELOG.md
Author-email: devjourney@live.com
License-Expression: MIT
License-File: LICENSE
Keywords: ai,audio,claude,fastmcp,home-assistant,mcp,model-context-protocol,music-assistant,smart-home
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Home Automation
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: fastmcp<4.0,>=2.0.0
Requires-Dist: music-assistant-client>=1.0.0
Description-Content-Type: text/markdown

# music-assistant-mcp

An [MCP](https://modelcontextprotocol.io/) server that wraps the [Music Assistant](https://music-assistant.io/) 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:

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

```json
{
  "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](https://github.com/devjourney/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](https://pypi.org/project/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)
