Music Assistant

Control Music Assistant (Home Assistant music server) - playback, volume, queue management, and library search. Use when user wants to play/pause music, skip...

Security Scan

The skill's requests and code are consistent with its stated purpose: it only needs a Music Assistant URL and token and uses them to control playback and query the server.

Purpose & Capability

Name/description (control Music Assistant) align with required environment variables (MA_URL, MA_TOKEN, optional MA_PLAYER) and the included CLI script which issues JSON-RPC commands to the Music Assistant API.

Instruction Scope

SKILL.md and scripts/mactl.py only instruct the agent to use MA_URL/MA_TOKEN (and optionally MA_PLAYER) to call the Music Assistant API; there are no instructions to read unrelated system files, other environment variables, or to send data to external endpoints beyond MA_URL.

Install Mechanism

No install spec is provided (instruction-only with an included script). Nothing is downloaded or written by an installer — the CLI is bundled as a local script.

Credentials

Only MA_URL and MA_TOKEN are required (plus optional MA_PLAYER). These credentials are directly necessary for the stated API interactions. No unrelated credentials or secrets are requested.

Persistence & Privilege

always is false and the skill does not request permanent system-level presence or modify other skills. The default ability for the agent to invoke the skill autonomously is unchanged (normal for skills) and not combined with other red flags.

Assessment

This skill appears to do exactly what it says: it uses MA_URL and MA_TOKEN to call your Music Assistant server. Before installing, ensure MA_URL points to your trusted Music Assistant instance (not a public/malicious host) and use a token with only the permissions you are comfortable granting (revoke or rotate it if needed). You can review the bundled scripts/mactl.py locally (it issues JSON-RPC to MA_URL and prints results) and run it on a machine you control. Note that the skill will use the provided token to control playback and query data on whatever MA_URL you supply, so avoid giving it tokens for services you don't trust.

Control your Music Assistant server for music playback, queue management, and library browsing.

Setup

Before using this skill, you need to configure your Music Assistant connection:

# Required
export MA_URL="http://YOUR_SERVER_IP:8095/api"
export MA_TOKEN="YOUR_BEARER_TOKEN"

# Optional - auto-detected if not set
export MA_PLAYER="your_player_id"

Finding your token:

1. Open Music Assistant web UI
2. Go to Settings → Security
3. Create or copy your Long-Lived Access Token

Finding your player ID:

./scripts/mactl.py players

Quick Start

# Basic controls
./scripts/mactl.py play          # Play/pause toggle
./scripts/mactl.py next          # Skip track
./scripts/mactl.py volume 75     # Set volume to 75%

# Search and play
./scripts/mactl.py search "nirvana"
./scripts/mactl.py play-search "pink floyd"  # Search and play first result

# Check what's playing
./scripts/mactl.py status
./scripts/mactl.py queue

Playback Controls

./scripts/mactl.py play          # Play/pause toggle
./scripts/mactl.py pause         # Pause
./scripts/mactl.py stop          # Stop playback
./scripts/mactl.py next          # Next track
./scripts/mactl.py prev          # Previous track

Volume

./scripts/mactl.py volume 75     # Set volume 0-100
./scripts/mactl.py mute          # Mute
./scripts/mactl.py unmute        # Unmute

Queue Management

./scripts/mactl.py shuffle true  # Enable shuffle
./scripts/mactl.py shuffle false # Disable shuffle
./scripts/mactl.py repeat all    # Repeat mode (off|all|one)
./scripts/mactl.py clear         # Clear queue
./scripts/mactl.py queue-items   # List queue contents

Search & Play

# Search library
./scripts/mactl.py search "pink floyd"
./scripts/mactl.py search "nirvana" --type track album
./scripts/mactl.py search "metallica" --limit 5

# Search and immediately play first result
./scripts/mactl.py play-search "smells like teen spirit"
./scripts/mactl.py ps "comfortably numb"  # shorthand

# Play by URI (for scripts/advanced use)
./scripts/mactl.py play-uri "spotify://track/4gHnSNHs8RyVukKoWdS99f"

Status & Info

./scripts/mactl.py status        # Show player status + now playing
./scripts/mactl.py queue         # Queue status
./scripts/mactl.py recent        # Recently played items
./scripts/mactl.py players       # List all available players

Library

./scripts/mactl.py sync          # Trigger library sync

Examples

"Play some Nirvana"

./scripts/mactl.py play-search "nirvana"

"What's playing?"

./scripts/mactl.py status

"Skip this track"

./scripts/mactl.py next

"Set volume to 50%"

./scripts/mactl.py volume 50

"Turn on shuffle"

./scripts/mactl.py shuffle true

Direct API Access

For operations not covered by the CLI, use the JSON-RPC API directly:

curl -s "http://YOUR_SERVER:8095/api" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MA_TOKEN" \
  -d '{"message_id":"1","command":"player_queues/all"}'

API documentation is available at: http://YOUR_SERVER:8095/api-docs

Key API Commands

Command	Args	Description
players/all	-	List all players
player_queues/all	-	List all queues
player_queues/play_pause	queue_id	Toggle play/pause
player_queues/next	queue_id	Next track
player_queues/previous	queue_id	Previous track
player_queues/stop	queue_id	Stop playback
player_queues/shuffle	queue_id, shuffle_enabled	Set shuffle
player_queues/repeat	queue_id, repeat_mode	Set repeat (off/all/one)
player_queues/clear	queue_id	Clear queue
player_queues/items	queue_id, limit, offset	Get queue items
player_queues/play_media	queue_id, uri	Play by URI
music/search	search, media_types, limit	Search library
music/recently_played_items	limit	Recent items
music/sync	media_types, providers	Sync library
config/players/get	player_id	Get player settings