laszlopere/mcp-kodi

An MCP server that lets an AI assistant
control a Kodi media player over Kodi's JSON-RPC API. Written
in C on the GLib stack.
There is **no user-facing CLI**: you talk to the AI, the AI calls this server's
tools, and the server speaks JSON-RPC to Kodi. The only interface is MCP over
stdio.
**Where this is going.** The plan is a complete, full-featured package that lets
any MCP-compatible AI transform the entire media-player experience — not just
press buttons, but reinvent how you discover, queue, and enjoy your media. Tell
the assistant what you're in the mood for and let it run the room: build the
evening's lineup, pick up where you left off last night, adapt on the fly, and
surface things you'd never have found yourself. We're aiming for something
genuinely new — a mind-blowingly different way to live with your media player.
> **Status — early, but already remarkable (v0.2.0dev).** A growing set of
> dedicated, purpose-built tools covers transport, volume, search, queue
> management, and playback history. What makes the build capable *beyond* that
> list is the **rpc escape hatch** (see below): an opt-in passthrough to *any*
> Kodi JSON-RPC method. Between the first-class tools and that escape hatch, an
> assistant can already drive nearly everything Kodi exposes — remarkable enough
> that we decided to publish early rather than wait for the full vision to land.
> Expect frequent releases.
---
What it can do
Each tool targets a configured Kodi box by key (instance); omit it and the
configured default box is used (with one exception: history spans **all**
boxes when instance is omitted).
**Transport & audio**
| Tool | What it does |
|------------|--------------|
| play | Press **Play** on the remote — resume or begin playback on the target box. |
| pause | Press **Pause** — pause the active player. |
| stop | Press **Stop** — stop the active player **and clear the playlist it was consuming**, so no queued items linger. |
| skipnext | Press **Skip Next** — advance to the next track/chapter in the active playlist. |
| skipprevious | Press **Skip Previous** — go to the previous track/chapter (or restart the current item). |
| volume | Adjust the volume by a **relative** signed step (percentage points); step 0/omitted just reads. Never an absolute level, so the assistant can't blast or silence the box by guessing. Returns volume, mute state, and the 0–100 bounds. |
| mute | Mute the box's audio output. |
| unmute | Unmute the box's audio output. |
| nowplaying | Report what is playing without changing anything — also a reachability + state probe. |
| notify | Show a notification toast on the box's screen — title + message, with an optional icon (info/warning/error or any image path/URL) and display time. Doesn't touch playback. |
**Search & discovery**
| Tool | What it does |
|----------------|--------------|
| searchmedia | Find playable **leaf files** by name across music / tv-show / movie, with paging (limit/offset) and a total count. Music title matches the **album**; the song arg matches a track by its **own title** library-wide (*"play Hey Jude"* needs no artist), narrowable by artist/title/number. For tv, title matches the **show**; the episodetitle arg finds an episode by its **own title** library-wide (narrowable by a show title). Movie/tv-show queries can also filter by actor/director. Resolves the library by name, so the assistant acts by title, not numeric id. Media items only — people lookups live in contributors. |
| contributors | Find or list **people** — bands, solo artists, composers, actors, directors — by optional name substring and/or type. Each row says where the name yields hits (albums/songs/movies/tvshows); feed the exact name back into searchmedia to drill. |
| audio_and_subtitle_info | 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 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. |