Press Play on the Kodi remote: resumes paused playback only — it cannot start new content (with nothing loaded it is a no-op); use playfile to start something. Returns the player-state snapshot { "state", "media", "id", "title", "artist", "time", "totaltime", … }.

Press Pause on the Kodi remote: pause the active player on the target instance. Returns the player-state snapshot { "state", "media", "id", "title", "artist", "time", "totaltime", … }.

Press Stop on the Kodi remote: stop the active player on the target instance and clear the playlist it was playing, so no queued items linger. Returns the player-state snapshot — { "state": "stopped" } after a successful stop.

Mute the target instance's audio output. Returns { "muted", "volume" }.

Unmute the target instance's audio output. Returns { "muted", "volume" }.

Adjust the target instance's volume by a relative step (in percentage points); step 0 or omitted just reports the current volume. Returns { "muted", "volume", "min", "max" }.

Report what is playing on the target instance without changing anything — also a reachability and state probe. Returns the player-state snapshot { "state", "media", "id", "title", "artist", "time", "totaltime", … }; { "state": "stopped" } when idle.

Read or modify the configured Kodi instances (action: get/set/remove). Manages the MCP server's own config, not a Kodi device. Returns { "default", "instances": [ { "key", "host", "scheme", "insecure", "has_auth", "allow_rpc", … } ] }.

Find playable files by name: music/tv-show/movie, drilled to leaf files with paging (limit/offset) and a total count. For music, title means the ALBUM name — songs cannot be matched by their own title. Movie and tv-show queries can also filter by actor/director. Finds media items only — for people lookups (bands, artists, who is in the library) use contributors. Returns { "type", "total", "returned", "offset", "truncated", "rows": [ { "file", "id", "label", "title", … } ] }.

Find or list contributors (bands, solo artists, composers, actors, directors): optional name substring, optional type (band/composer/actor/director) — e.g. {type: "band"} lists all bands. Rows {name, in: [albums|songs|movies|tvshows]} say where each name yields hits — feed the exact name back into searchmedia to drill. Returns { "total", "returned", "offset", "truncated", "rows" }.

Play one file by path (e.g. a searchmedia result's file): Player.Open auto-selects the audio/video player. Works for any reachable path, in-library or not. A file missing from disk (stale library entry) is reported as an error. Returns the player-state snapshot { "state", "media", "id", "title", "artist", "time", "totaltime", … }.

Queue an item behind the one now playing, for continuous playback: a searchmedia row's library id (type+id) or a file path; next:true plays it right after the current item. Something must already be playing (start with play/playfile). An item whose file is missing from disk (stale library entry) is refused. Returns the player-state snapshot, unchanged by the add — the current item keeps playing.

Read the queue without changing it: the items of the active player's playlist — or of a named one (audio/video/picture), which always wins — plus the position of the now-playing item. An empty queue is an empty list. Returns { "type"?, "total", "position"?, "items": [ { "id", "file", "label", "type" } ] }.

Empty all queues: clear the audio, video and picture playlists in one call. The current item keeps playing — only the queued items behind it are removed — so playback is never interrupted. Not undoable; inspect with getplaylist first if the content matters. Returns the player-state snapshot — whatever was playing still is, with nothing queued behind it.

List recently played items from the local playback log. Filter with an ISO-8601 window (since/until), media/kind/artist, a free-text match or an exact id; page with limit/offset/order, or ask for a count only. An omitted instance returns all boxes. Reads only the local log — no Kodi call, so it works even when no box is reachable. Returns { "total", "returned", "offset", "truncated", "entries": [ { "at", "instance", "kind", "media", "title", "artist", … } ] }.

Escape hatch: send a raw JSON-RPC method to Kodi and return its reply unchanged. Disabled unless the target instance has opted in (allow_rpc in the server config, set by hand only).