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", "type", "time", "totaltime", "progress", "nowplaying": { "media", "id", "title", "artist", … } }.

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

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.

Press Skip Next (Next track / chapter) on the Kodi remote: advance the active player to the next item in its playlist (or next chapter). A remote keypress, not a player command; with nothing loaded it is a no-op. Returns the player-state snapshot { "state", "type", "time", "totaltime", "progress", "nowplaying": { "media", "id", "title", "artist", … } }.

Press Skip Previous (Previous track / chapter) on the Kodi remote: go to the previous item in the playlist (or restart the current item, matching Kodi's own button). A remote keypress, not a player command; with nothing loaded it is a no-op. Returns the player-state snapshot { "state", "type", "time", "totaltime", "progress", "nowplaying": { "media", "id", "title", "artist", … } }.

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", "type", "time", "totaltime", "progress", "audio", "subtitle" (audio/subtitle for video: count + current track), "nowplaying": { "media", "id", "title", "artist", … } }; { "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; match a song by its own title with the song arg ("play Hey Jude" needs no artist). Find a tv episode by its own name with the episodetitle arg. 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", "type", "time", "totaltime", "progress", "nowplaying": { "media", "id", "title", "artist", … } }.

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.

Show a notification toast on the Kodi box's screen: a title and message, with an optional icon ("info"/"warning"/"error" or any image path/URL) and display time in milliseconds. Doesn't touch playback. Returns { "shown", "title", "message", "displaytime", "image"? }.

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", … } ] }.

Inspect a movie or episode's audio tracks and subtitles BEFORE playback, from Kodi's cached streamdetails (no playback). Name the item by type+id (a searchmedia movie/episode row) or by file. Returns { "file", "audio":[{ "index", "codec", "channels", "language" }], "subtitle":[{ "index", "language" }], "video":[…] }. Embedded streams only: external .srt sidecars and files Kodi hasn't scanned come back as empty arrays; "index" maps to the audio/subtitle setters for embedded streams.

Switch the audio track and/or subtitle of the video now playing on the target instance. "audio" is a stream index; "subtitle" is a stream index or "off" to hide subtitles — use the "index" values from audio_and_subtitle_info. Omit an argument to leave that stream unchanged; give at least one. Returns the player-state snapshot.

Play a video file by path AND select its audio track and/or subtitle once it starts — the "when starting playback" partner of set_audio_and_subtitle. "file" is required; "audio" is a stream index and "subtitle" is a stream index or "off", using the "index" values from audio_and_subtitle_info. Give at least one of audio/subtitle (else use playfile). Video only. Returns the player-state snapshot.

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).