mcp-kodi is an MCP (Model Context Protocol) server for controlling the Kodi media player through Kodi's JSON-RPC API. The project is written in the C language on the GLib stack and is an independent, clean-room implementation of free software, released under the GNU GPL v3.0 license.
Purpose mcp-kodi's goal is to let any MCP-compatible AI assistant control the Kodi media player. It is not a user-facing CLI tool: the user talks to the AI, the AI calls the tools provided by this server, and the server then sends JSON-RPC requests to Kodi. The only interface is MCP over stdio. The project's vision is not merely "pressing buttons", but letting AI reshape the media playback experience—orchestrating playlists according to the user's mood and preferences, resuming from where playback last stopped, adjusting content in real time, and recommending content the user would have trouble discovering on their own.
Main capabilities The current version (v0.2.0dev) already provides a set of clearly purposed tools, covering the following areas:
- Playback control and audio: play / pause / stop, playfile, volume, mute / unmute, etc.
- Search and discovery: searchmedia, contributors.
- Playback and queue: queue, getplaylist, dropplaylists, etc.
- Records and escape hatch: history, nowplaying, rpc.
Most action tools return a small player state snapshot of the form { "state": "playing"|"paused"|"stopped", "type", "time", "totaltime", "progress", "nowplaying": { "media", "id", "file", "label", "title", … } }, with the loaded media information nested under nowplaying, along with fields applicable by media type such as artist, album, track, showtitle, season, episode; progress gives a readable form like "15:38 / 46:40 (33%)". Volume tools return { "muted", "volume" } (volume also comes with min / max bounds). Read tools (searchmedia, contributors, getplaylist, history) return their respective paginated result wrappers.
Except for rpc, every tool declares these result shapes with an MCP outputSchema (specification revision 2025-06-18), and returns each successful result both as structuredContent and as a JSON text block, so that schema-aware clients can validate and use the results without parsing. rpc declares no shape: it returns Kodi's raw reply as-is.
Each tool specifies one configured Kodi device via the key (instance); if omitted, the configured default device is used (with one exception: when instance is omitted, history spans all devices).
The rpc escape hatch rpc POSTs any JSON-RPC method you specify to the target device and returns Kodi's unshaped result as-is. This feature is powerful and unconstrained, so it is disabled by default and enabled per device: only when a device's configuration object has "allow_rpc": true is rpc allowed for that device. This flag can only be granted by manually editing config.json—it is intentionally designed as a field that the instances tool cannot write, so the AI can never enable the escape hatch on its own. Calling rpc on a device that has not enabled it returns a clear error and sends no request to Kodi. For the complete Kodi method surface, see docs/kodi-jsonrpc-catalog.md.
Usage Prepare Kodi for remote control: in Kodi, open "Settings → Services → Control", enable "Allow remote control via HTTP", and set the username and password there. These credentials will be written into this server's configuration in the form user:pass as auth.
Because mcp-kodi uses HTTPS, regular use requires placing a small reverse proxy in front of Kodi's plain HTTP control port. Using Caddy with tls internal is a convenient choice: it terminates HTTPS and forwards to Kodi on the local machine. Point the device's host at that proxy, and set insecure: true to accept its self-signed certificate. For a complete step-by-step guide (Kodi menus, installing Caddy, Caddyfile), see docs/kodi-server-setup.md.
There are two ways to register a Kodi device:
- Let the AI do it: once the MCP server is loaded, tell the assistant your Kodi address and login information, and it will register the device through the instances tool (set), writing the entry into the configuration file.
- Manually edit config.json. Two items are intentionally made non-operable by the AI and can only be edited manually: the password (auth is write-only, and the instances tool never returns the stored password, so the assistant can register a device but can never read back the credentials); and the escape hatch (allow_rpc is not a field the instances tool can write, so the assistant can never grant itself unrestricted rpc passthrough).
The configuration file is located at ${XDG_CONFIG_HOME:-~/.config}/mcp-kodi/config.json, stores a mapping of named Kodi devices, and specifies a default. The file is created with 0600 in a 0700 directory (because it contains passwords), and is written back atomically when the instances tool modifies it. If there is no configuration file, a device can be defined entirely through environment variables, applied to the implicit default device: KODI_HOST, KODI_AUTH, KODI_SCHEME, and -k in KODI_CURL_OPTS (→ insecure). If there is neither a file nor environment variables, the server exits with an explicit error telling you to configure it. Legacy version: 1 flat files (a single top-level host / auth /…) are read as one device named default and rewritten to the version: 2 structure on the next save. Note: the configuration is read only once at startup; after manually editing config.json (for example, to set allow_rpc), the server must be restarted to re-read it.
Registering with an MCP client: in Claude Desktop or another MCP client, add a stdio server entry pointing to the binary. Once registered, you can give the assistant instructions such as "What is the player in the living room playing?" (nowplaying), "Find Pink Floyd's Animals and play it" (searchmedia → playfile), or "Mute the bedroom" (mute).
Use cases Suitable for controlling Kodi media players on a home LAN: the devices are usually on a home LAN behind a router/firewall and are not exposed to the internet, so enabling the HTTP control interface on them is usually safe. Login name/password and an HTTPS proxy provide defense in depth. Suitable for users who want to use natural language to have an AI manage media playback, search, queues, and playback history.
Limitations and caveats
- config.json stores the Kodi password in plaintext (permissions 0600) and should be protected like any other credentials file.
- insecure: true disables TLS certificate verification for that device. Behind Caddy's tls internal self-signed certificate this is the correct choice, but it means the connection is encrypted rather than CA-authenticated—keep the proxy on a trusted network.
- The rpc escape hatch can call arbitrary JSON-RPC methods (including destructive methods such as System.Shutdown). It is disabled by default and is enabled only after manually setting allow_rpc: true for a specific device. Enable it only if you trust the assistant to operate without restrictions.
- This is currently an early v0.2.0dev version, and features are still evolving rapidly.
The project is developed by Laszlo Pere, released under the GNU GPL v3.0 license, and comes with no warranty. You can support the project through GitHub Sponsors.
(Note: the materials do not provide specific installation commands, a dependency list, or more details on tool parameters, so none have been added here.)
