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

Search & discovery

Playback & queue

Bookkeeping & escape hatch

Most action tools return a small player-state snapshot — { "state": "playing"|"paused"|"stopped", "type", "time", "totaltime", "progress", "nowplaying": { "media", "id", "file", "label", "title", … } } — keeping the player status (state/type/time/totaltime plus a legible progress clause like "15:38 / 46:40 (33%)") at the top and nesting the loaded media under nowplaying, with its per-media fields where they apply (artist, album, track, showtitle, season, episode) — so the assistant always sees the effect of its action: this covers play/pause/stop, playfile, queue, dropplaylists, and nowplaying. The audio tools volume/mute/unmute return { "muted", "volume" } (volume also adds the min/max bounds). The read tools (searchmedia, contributors, getplaylist, history) return their own paged result envelopes.

Every tool except rpc declares these shapes as an MCP outputSchema (spec revision 2025-06-18) and mirrors each successful result as structuredContent alongside the JSON text block, so schema-aware clients can validate and consume results without parsing. Each description also states the result shape inline — the channel every client shows the model. rpc declares none: it returns Kodi's raw reply verbatim, which has no fixed shape.

The rpc escape hatch

rpc POSTs any JSON-RPC method you name to the target box and hands back Kodi's raw result, unshaped:

// e.g. raise the GUI volume, activate a window, send an input action…
rpc { "instance": "hall", "method": "GUI.ActivateWindow", "params": { "window": "home" } }

This is powerful and unconstrained, so it is disabled by default and gated per instance. A box permits rpc only when its config object carries "allow_rpc": true. That flag is granted only by hand-editing config.json — it is intentionally not one of the fields the instances tool can write, so the assistant can never enable its own escape hatch. Opting a box in is an explicit, out-of-band human decision; calling rpc on a box that hasn't opted in returns a clean error and makes no Kodi request.

See the full Kodi method surface in docs/kodi-jsonrpc-catalog.md.

Related MCP server: mcp-mpv-player

Configuration

Set up Kodi for remote control

Before mcp-kodi can reach a box, that Kodi has to allow remote control. In Kodi, open Settings → Services → Control and turn on Allow remote control via HTTP, then set a username and password right there. Those same credentials go into this server's config as auth, in user:pass form.

mcp-kodi speaks HTTPS, so for normal use you put a small reverse proxy in front of Kodi's plain-HTTP control port. Caddy with tls internal is the easy choice: it terminates HTTPS and forwards to Kodi on localhost. Point the instance's host at the proxy and set insecure: true to accept its self-signed certificate. The full step-by-step walkthrough — the exact Kodi menus, installing Caddy, and the Caddyfile — is in docs/kodi-server-setup.md.

Most Kodi players already sit on a home LAN behind a router/firewall and are not exposed to the internet, so turning on the HTTP control interface there is generally safe. The login/password and the HTTPS proxy add defence in depth — just keep the proxy on a trusted network and don't forward its port to the open internet.

Registering a Kodi instance

There are two ways to add a box. The simplest is to let the AI do it: once the MCP server is loaded, just tell the assistant about your Kodi — its address and login — and it registers the instance for you through the instances tool (set), writing the entry into the config file.

You can also do it by hand, by editing config.json directly. Two things are deliberately off-limits to the AI, so hand-editing is the only way to set them:

• The password. auth is write-only — the instances tool never returns a stored password, so the assistant can register a box but can never read back the credentials. If you'd rather the AI never see the password at all, type it into the file yourself.

• The escape hatch. allow_rpc is not a field the instances tool can write, so the assistant can never grant itself the unrestricted rpc passthrough. Enabling it is always an explicit, out-of-band human edit.

The config file

The server reads ${XDG_CONFIG_HOME:-~/.config}/mcp-kodi/config.json. It holds a map of named Kodi instances and names one default:

{
  "version": 2,
  "default": "hall",
  "instances": {
    "hall":    { "name": "Living Room TV", "host": "hall.example.local:8443", "auth": "kodi:<password>", "scheme": "https", "insecure": true, "allow_rpc": true },
    "bedroom": { "name": "Bedroom",        "host": "bedroom.example.local:8443", "auth": "kodi:<password>", "scheme": "https", "insecure": true }
  }
}

The file is created 0600 in a 0700 directory (it holds passwords) and is written back atomically when the instances tool changes it.

No config file? A single box can be defined entirely from the environment, applied to an implicit default instance: KODI_HOST, KODI_AUTH, KODI_SCHEME, and -k in KODI_CURL_OPTS (→ insecure). With neither a file nor env, the server exits with a clear error telling you to configure.

A legacy version: 1 flat file (single top-level host/auth/…) is read as one instance named default and rewritten in the version: 2 shape on the next save.

Note: config is read once at startup. After hand-editing config.json (e.g. to set allow_rpc), restart the server so it re-reads the file.

Registering with an MCP client

Claude Code

# user scope makes the tools available in every project
claude mcp add --scope user kodi -- /path/to/mcp-kodi/src/mcp-kodi

Claude Desktop / other MCP clients

Add a stdio server entry pointing at the binary:

{
  "mcpServers": {
    "kodi": {
      "command": "/path/to/mcp-kodi/src/mcp-kodi"
    }
  }
}

Once registered, ask your assistant things like "what's the player doing in the living room?" (nowplaying), "find Pink Floyd's Animals and play it" (searchmedia → playfile), or "mute the bedroom" (mute).

Security notes

• config.json stores Kodi passwords in plaintext, mode 0600. Protect it like any other credential file.

• insecure: true disables TLS certificate verification for that box. It is the right choice behind Caddy's tls internal self-signed cert, but means the connection is encrypted, not authenticated against a CA — keep the proxy on a trusted network.

• The rpc escape hatch can invoke any JSON-RPC method (including destructive ones like System.Shutdown). It stays off until you deliberately set allow_rpc: true for a specific box. Enable it only where you trust the assistant to operate unconstrained.

License

Copyright © 2026 Laszlo Pere <laszlopere@gmail.com>. An independent, clean-room implementation.

Free software, licensed under the GNU General Public License v3.0. You may redistribute and/or modify it under those terms; it comes with no warranty. See LICENSE for the full text.

Support this project

If this project is useful to you, please consider supporting it through GitHub Sponsors. Every bit of support keeps it alive — funding the time to ship the frequent releases this is built on, and to chase the full vision.

And if you're still on the fence: ask your Claude whether this project is good for you — and if it recommends it (as most Claude do), support it by becoming a sponsor.