MCP Kodi

What laszlopere/mcp-kodi MCP server does

laszlopere/mcp-kodi MCP server connects an MCP-compatible assistant to one or more Kodi media players. The assistant invokes MCP tools, while the server sends the corresponding requests to Kodi's JSON-RPC API. There is no interactive CLI; MCP over standard input and output is the only user-facing interface.

The server can address a configured Kodi box using an instance key. If a tool call omits that key, the configured default is used. Playback history is the exception: without an instance, it searches the local logs for all configured boxes.

How it works

The server exposes focused operations for transport controls, volume, mute state, notifications, media discovery, queues, and playback records. Many action calls return a compact player snapshot containing playback state, timing, progress, and details about the current item. Read-oriented calls return their own paged result structures.

Search operates against Kodi's media library and resolves items by names rather than requiring numeric IDs. Results can be used with playback and queue tools, while direct file paths are also supported for reachable media. Playback-affecting calls write to a local history log, allowing history queries even when Kodi is temporarily unreachable.

laszlopere/mcp-kodi MCP server also includes an optional raw JSON-RPC escape hatch. The rpc operation returns Kodi's response without imposing a schema, but it is disabled by default and must be enabled per instance through configuration.

Setup and configuration

The project is written in C using GLib and builds from source with autotools or through a .deb package. The server is intended to be launched as a local stdio MCP process and then configured in an MCP client. The supplied material does not specify a package-manager command or a complete client configuration example.

Instance settings are managed through the instances tool, which can read, add, or remove the server's instance configuration. Stored passwords are not returned. The allow_rpc setting is deliberately excluded from assistant-managed instance updates; enabling raw RPC requires manually editing config.json.

Tools and capabilities

Available capabilities include:

• Start, pause, stop, and skip playback.
• Adjust volume by a relative percentage step, read volume, mute, and unmute.
• Display notifications on a Kodi screen.
• Search music, television, and movie libraries with paging and filters.
• Find contributors such as artists, composers, actors, and directors.
• Inspect embedded audio, subtitle, and video stream details before playback.
• Change the active video's audio track or subtitle.
• Play files, append or prioritize queue items, inspect playlists, and clear queues.
• Query locally recorded playback history with time, media, contributor, text, ID, and paging filters.
• Send arbitrary JSON-RPC methods when the per-instance escape hatch is enabled.

Most tools other than rpc declare MCP output schemas and return structured content in addition to a JSON text result. The raw RPC operation has no fixed output shape because Kodi determines its response.

Limitations and notes

Search and stream inspection depend on Kodi's library data. Audio and subtitle inspection covers embedded streams cached in Kodi; external subtitle sidecars and unscanned files may produce empty arrays. Queue operations that reference files require those files to exist at reachable paths. Queueing also requires something to already be playing.

Stopping playback clears the playlist being consumed, while clearing all playlists leaves the current item playing and removes only queued items. The rpc tool is unrestricted when enabled, so its manual per-instance opt-in is an important configuration boundary.

The project is identified as an early development release, so behavior and tool coverage may change between releases.