What is the primary benefit of using this skill with my AI agent?

This skill allows AI agents to interact directly with your self-hosted Music Assistant server via natural language, bridging the gap between coding assistants and your home audio hardware like Sonos, HomePod, and AirPlay speakers.

What are the technical requirements to use this automation?

You need an active Music Assistant server (v2.x) running via Docker or Home Assistant, a long-lived API token, and a Python environment to run the included client scripts.

Which AI coding agents are compatible with this skill?

The skill is designed to work with any agent that can execute Python or shell commands, including Claude Code, Cursor, VS Code Copilot, and the Codex CLI.

Can I control multiple speakers or specific rooms simultaneously?

Yes, the skill supports full multi-room control, allowing you to target specific rooms, manage groups, and adjust volume levels for individual speakers through simple prompts.

What specific files and documentation are included in this package?

You receive the SKILL.md definition, a dedicated guide on handling Music Assistant API nuances, and a CLI script (ma-play.py) for testing and verifying your connection.

Does this skill require a subscription or a cloud account to operate?

No, this skill communicates directly with your local Music Assistant server (typically over your LAN), ensuring your data and playback commands stay private and off third-party clouds.

Music Assistant Automation Skill for AI Agents

About this skill

🎵 Control your self-hosted Music Assistant server from any compatible AI coding agent — Claude Code, Codex CLI, Cursor, VS Code Copilot, and more.

This skill gives your AI agent hands-on control over your existing Music Assistant setup (Spotify, Internet Archive, local library, AirPlay, UPnP, HomePod, Chromecast, Sonos). One natural-language prompt is enough: "play Tame Impala on Living Room", "pause Küche", "set Bedroom volume to 25".

✨ Highlights • Works with YOUR self-hosted MA server — no cloud signup, no extra service • Supports 25+ providers: Spotify, Internet Archive, radio, local files, podcasts • Multi-room audio (groups, individual control, sync playback) • Built-in playback control (play/pause/skip/volume/queue/shuffle/repeat) • Best-practice error handling around Music Assistant API gotchas (constructor signature, WebSocket listener lifecycle, Spotify URI prefix)

🛠 Requirements • A self-hosted Music Assistant server (v2.x — Home Assistant add-on, Docker, or standalone). Free & open source: https://music-assistant.io • A long-lived API token from MA Settings → Users → Create token • Local network reachability from agent → MA server (usually LAN)

🔌 Setup (one-time)

Install dependencies: pip install music-assistant-client websockets aiohttp orjson
Store your MA token securely (env var MUSIC_ASSISTANT_TOKEN, or ~/.ma_token with chmod 600). Never paste into chat.
Run the included ma-play.py "Daft Punk" --player "Living Room" --dry-run to verify connection
Start scripting — see SKILL.md for full pattern

🏠 Perfect for Home Assistant users Music Assistant is a popular HA add-on. Combine both for music automation from any HA script or scene.

📦 What's included • SKILL.md — main skill definition with onboarding wizard • references/api-gotchas.md — detailed API gotchas + verified working examples • scripts/ma-play.py — minimal CLI for search-and-play (great for testing)

Frequently Asked Questions

music assistant automation