Kodi

Provides REST and MCP protocol access to control Kodi playback, library, and smart downloads.

python

GitHub Stars

python

Language

4 months ago

First Indexed

3 weeks ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "laheud-kodi-mcp-server": {
      "command": "docker",
      "args": [
        "exec",
        "kodi-mcp-server",
        "python",
        "-m",
        "src.pure_mcp_server"
      ],
      "env": {
        "KODI_HOST": "<host>",
        "KODI_PORT": "8080",
        "LOG_LEVEL": "INFO",
        "SERVER_HOST": "0.0.0.0",
        "SERVER_PORT": "8080",
        "KODI_PASSWORD": "your_password",
        "KODI_USERNAME": "kodi",
        "MCP_SERVER_NAME": "kodi-controller",
        "KODI_DOWNLOADS_PATH": "/storage/downloads"
      }
    }
  }
}

You can control Kodi through a dedicated MCP server that exposes both a REST API and MCP protocol. This lets you manage playback, library operations, and smart downloads from MCP clients and automation tools with real-time feedback.

How to use

Connect to the MCP server from your MCP client or automation tool. Use the available tools to control playback, navigate the Kodi interface, manage your library, and handle downloads. You can trigger actions like play, pause, or stop, adjust volume, search for movies or TV episodes, and run smart downloads operations that find and play the best match automatically.

How to install

Prerequisites you need before installing: Python 3.11 or newer and Kodi with JSON-RPC enabled. You also need network access to the Kodi instance.

Install dependencies

pip install -r requirements.txt

Configure environment variables for Kodi access and downloads path as shown below.

export KODI_HOST=192.168.1.100
export KODI_PORT=8080
export KODI_USERNAME=kodi
export KODI_PASSWORD=your_password
export KODI_DOWNLOADS_PATH=/path/to/downloads

Run the server using the Python module entry point.

python -m src.server

Configuration and runtime notes

Configure the Kodi JSON-RPC endpoint to be accessible remotely by enabling remote control in Kodi and setting the proper port, username, and password. Ensure the downloads path you configure matches where Kodi stores downloaded videos.

If you plan to run the server in Docker, create and customize a .env file to supply Kodi connection details and adjust the server binding as needed.

Additional content

Available environment variables to customize behavior are listed under the configuration section. You can set or override them to match your network and Kodi setup.

Available tools

get_now_playing

Get currently playing media information from Kodi.

player_play_pause

Toggle playback between play and pause.

player_stop

Stop playback.

set_volume

Set the playback volume (0-100).

navigate_menu

Navigate the Kodi interface (up, down, left, right, select, back).

search_movies

Search movies in the Kodi library.

list_recent_movies

List recently added movies.

list_tv_shows

List all TV shows in the library.

play_movie

Play a movie by library ID.

play_episode

Play a TV show episode.

get_library_stats

Get library statistics.

scan_library

Trigger a library scan.

list_downloads

List video files in the downloads directory.

search_downloads

Search downloads by filename.

play_file

Play a video file by its path.

find_and_play

Smart search with automatic playback of the best match.

Built by

VeilStrat

AI signals for GTM teams