Kodi MCP Server

A Model Context Protocol (MCP) server for controlling Kodi media center. This server provides both REST API and MCP protocol support, allowing seamless integration with MCP clients like Claude Desktop, n8n, and other MCP-compatible tools.

Features

Core Kodi Controls

• Player Control: Play, pause, stop, volume control
• Navigation: Menu navigation (up, down, left, right, select, back)
• Library Management: View library statistics, scan library
• Movie Operations: Search movies, list recent movies, play by ID
• TV Show Operations: List TV shows, play episodes

Smart Downloads Management

• List Downloads: Browse video files in download directory
• Search Downloads: Find files by name (case-insensitive)
• Smart Find & Play: Intelligent search with automatic playback of best match
• Direct File Play: Play any video file by path

Protocol Support

• REST API: Direct HTTP endpoints for easy integration
• MCP Protocol: Full Model Context Protocol support
• Server-Sent Events: Real-time event streaming
• WebSocket: Bidirectional communication support

Quick Start

Using Docker (Recommended)

1. Clone the repository

   git clone https://github.com/your-username/kodi-mcp-server.git
   cd kodi-mcp-server
   

2. Configure environment

   cp .env.example .env
   # Edit .env with your Kodi configuration
   

3. Start with Docker Compose

   docker-compose up -d
   

4. Verify installation

   curl http://localhost:8080/health
   

Manual Installation

1. Requirements

   • Python 3.11+
   • Kodi with JSON-RPC enabled
   • Network access to Kodi instance

2. Install dependencies

   pip install -r requirements.txt
   

3. Configure environment

   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
   

4. Run the server

   python -m src.server
   

Configuration

Environment Variables

Kodi Setup

1. Enable JSON-RPC in Kodi

   • Settings Services Control
   • Enable "Allow remote control via HTTP"
   • Set username and password
   • Note the port (usually 8080)

2. Configure Downloads Path

   • Use the actual path as seen by Kodi
   • For Docker Kodi: usually /storage/downloads/ or /var/media/
   • Test with Files.GetDirectory in Kodi JSON-RPC

Available Tools

Player Control

• get_now_playing - Get currently playing media information
• player_play_pause - Toggle play/pause
• player_stop - Stop playbook
• set_volume - Set volume level (0-100)

Navigation

• navigate_menu - Navigate Kodi interface (up/down/left/right/select/back)

Library Operations

• search_movies - Search movies in Kodi library
• list_recent_movies - List recently added movies
• list_tv_shows - List all TV shows
• play_movie - Play movie by library ID
• play_episode - Play TV show episode
• get_library_stats - Get library statistics
• scan_library - Trigger library scan

Downloads Management

• list_downloads - List video files in downloads directory
• search_downloads - Search downloads by filename
• play_file - Play video file by path
• find_and_play - Smart search with automatic best-match playback

Usage Examples

With MCP Client (Claude Desktop, n8n)

{
  "tool": "find_and_play",
  "arguments": {
    "query": "avengers",
    "auto_play": true
  }
}

REST API

# Search and play the best matching file
curl -X POST http://localhost:8080/tools/find_and_play \
  -H "Content-Type: application/json" \
  -d '{"params": {"query": "batman", "auto_play": true}}'

# List recent movies
curl -X POST http://localhost:8080/tools/list_recent_movies \
  -H "Content-Type: application/json" \
  -d '{"params": {"limit": 10}}'

# Control playback
curl -X POST http://localhost:8080/tools/player_play_pause \
  -H "Content-Type: application/json" \
  -d '{}'

MCP JSON-RPC Protocol

# Initialize connection
curl -X POST http://localhost:8080/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "initialize", "id": 1}'

# List available tools
curl -X POST http://localhost:8080/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 2}'

# Execute tool
curl -X POST http://localhost:8080/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", 
    "method": "tools/call", 
    "params": {
      "name": "find_and_play",
      "arguments": {"query": "matrix", "auto_play": true}
    },
    "id": 3
  }'

Integration

n8n MCP Client

1. Add MCP Client node in n8n
2. Configure connection:
   • Transport: Server-Sent Events
   • URL: http://your-server:8080
3. Use available tools in your workflows

Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "kodi-controller": {
      "command": "docker",
      "args": ["exec", "kodi-mcp-server", "python", "-m", "src.pure_mcp_server"],
      "env": {}
    }
  }
}

Smart Search Algorithm

The find_and_play tool uses an intelligent scoring algorithm:

• ** Position Matching**: Terms at the beginning get higher scores -…