This page lists all MCP tools exposed by MZAP's built-in MCP server.
Which of these a client can see and call depends on its API key's role when authentication is enabled. The Role column shows the lowest role that can use each tool. Operators and Viewers only see and act on the players and zones assigned to them.
Players, zones, playlists and jingles are identified by their ID (a GUID). Call get_system_status first to find IDs and the current state.
Several tools take words rather than JSON booleans, because LLM clients frequently send boolean arguments as quoted strings, which failed with a JSON error before the tool ran:
| Tool | Parameter | Accepts |
|---|
set_player_volume, set_zone_volume | mute | "mute" / "unmute" |
set_equalizer, set_compressor, set_auto_level | enabled | "on" / "off" |
Common variants (true/false, yes/no, 1/0, enable/disable) are also accepted, and an unrecognized value returns a readable error instead of failing to parse.
| Tool | Role | What it does |
|---|
get_system_status | Viewer | Current state of everything: playlist players (playback state, current track, volume), other players (input, loopback, AirPlay, SoundMachine with its source and state), zones (volume, mute) and the routing matrix. |
The mzap://workspace resource gives the same overview as text, including AirPlay and SoundMachine session state per player.
| Tool | Role | What it does |
|---|
control_playback | Operator | Controls a player. action is play (also resumes from pause), resume, pause, stop, next, previous or seek. For seek, pass position in seconds. |
| Tool | Role | What it does |
|---|
set_player_volume | Operator | Sets a player's volume and/or mute state. volumeDb runs from 0 (full) to -40 (silent); lower values are clamped to silence. mute takes "mute" / "unmute". |
set_zone_volume | Operator | Same for a zone. |
| Tool | Role | What it does |
|---|
manage_routing | Operator | Connects a player to zones (action: route) or disconnects it (action: unroute). zoneIds is a comma-separated list. An Operator needs both the player and the zones assigned. |
| Tool | Role | What it does |
|---|
create_player | Admin | Creates a playlist player. Assign a playlist with assign_playlist and route it with manage_routing. |
create_process_loopback_player | Admin | Creates a player that captures one application's audio, for example Spotify.exe. Needs Windows 10 build 19041 or later and the matching license feature. |
create_airplay_player | Admin | Creates an AirPlay input. Optional: the name shown in the AirPlay picker, whether the phone's volume slider drives the player volume (off by default), and an endpoint password. |
create_soundmachine_player | Admin | See SoundMachine. |
| Tool | Role | What it does |
|---|
create_playlist | Admin | Creates an empty playlist. |
manage_tracks | Admin | Adds tracks (action: add, comma-separated file paths or stream URLs) or reorders them (action: reorder, comma-separated 0-based track positions in the new order). |
assign_playlist | Admin | Assigns a playlist to a player. |
set_playback_mode | Operator | Sets a playlist's playback mode: Sequential, RepeatOne, RepeatAll, Shuffle or StopAfterCurrent. |
| Tool | Role | What it does |
|---|
set_equalizer | Operator | Sets a zone's 10-band equalizer: either a preset by name (flat resets it) or 10 comma-separated band gains in dB (−15 to +15). enabled turns it on or off. |
set_compressor | Operator | Sets a zone's compressor: a preset by name (off disables it) or individual threshold, ratio, attack, release and makeup gain. enabled turns it on or off. |
set_auto_level | Operator | Sets a player's Auto level: enabled, target loudness (−24 to −10 LUFS), max boost (0 to 18 dB) and reaction speed (Slow, Normal or Fast). Omitted values stay as they are. |
| Tool | Role | What it does |
|---|
play_jingle | Operator | Plays a jingle over players or zones, ducking what is playing. targetType is players (default) or zones; without targetIds the jingle's saved targets are used. Without jingleId it lists the jingles. |
create_tts_jingle | Admin | Creates a text-to-speech jingle from name and text, with optional provider, voiceId, language and rate (0.5 to 2.0). Returns the new jingle's ID for play_jingle. Cloud voices need the matching license feature and an API key. |
list_tts_voices | Viewer | Lists the voices of a TTS provider (Windows by default, or a cloud provider), so you can pick a voiceId. |
| Tool | Role | What it does |
|---|
search_library | Viewer | Searches the media library with the same search syntax as the app (artist:pink AND title:wall, "pink floyd", word*). Optional artist, album and genre filters; up to 200 results (50 by default). |
search_radio_stations | Viewer | Searches the radio-browser.info directory by name, genre tag, country or language. Returns station names and stream URLs; add a URL to a playlist with manage_tracks. Up to 30 results (10 by default). |
These tools work with SoundMachine players and need the SoundMachine license feature.
| Tool | Role | What it does |
|---|
list_soundmachine_accounts | Admin | Lists the SoundMachine accounts with their display name, username, and how many players use each (up to 10), with the players' names. Never returns the password. |
find_soundmachine_sources | Operator | Finds stations, mixes or weekly schedules (kind: station, mix or schedule) with their IDs. Pass a playerId to browse that player's account; Admins may pass an account instead. A station query searches all of SoundMachine; without one you get the account's own stations. Mixes and schedules come from the account, filtered by the query. At most 25 results. |
set_soundmachine_source | Operator | Switches a SoundMachine player to a station, mix or schedule. If the player is playing, the new source starts at once; this does not count as a skip. |
soundmachine_like | Operator | Likes the current song, or removes the like if it is already liked. |
soundmachine_dislike | Operator | Blocks the current song for the account and skips it if the skip limit (6 per hour) allows; otherwise it finishes playing. |
create_soundmachine_player | Admin | Creates a SoundMachine player on an account (by ID, display name or username) playing a station, mix or schedule. Up to 10 players per account. Route it with manage_routing, then start it with control_playback. |
The source kind must be one of the names station, mix or schedule (case does not matter). Like, dislike and Next are not available while a SoundMachine message plays.
A player waiting for music shows State: Standby in get_system_status with the reason: nothing scheduled, waiting for network, service unavailable, or checking now. control_playback with play on a Standby player asks SoundMachine right away; pause and next report that there is nothing to pause or skip.
| Tool | Role | What it does |
|---|
get_workspace_info | Viewer | action: info (default) shows the current workspace's name, file and unsaved-changes state; action: list lists the saved workspace files. |
manage_workspace | Admin | action: save saves the current state (optionally to a new filename); action: load loads a saved workspace, replacing all players, zones, routing, playlists and settings. |
