Metadata-Version: 2.4
Name: music-assistant-mcp
Version: 0.1.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.

## Installation

```bash
pip install music-assistant-mcp
```

Or run directly with [`uvx`](https://docs.astral.sh/uv/):

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

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

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

```json
{
  "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
