Skip to main content
Glama

Kodi MCP Server

by laHeud
GitHub
Python
MIT License
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

Variable

Description

Default

Required

KODI_HOST

Kodi server IP address

localhost

Yes

KODI_PORT

Kodi JSON-RPC port

8080

Yes

KODI_USERNAME

Kodi username

-

Yes

KODI_PASSWORD

Kodi password

-

Yes

KODI_DOWNLOADS_PATH

Path to downloads folder

-

Yes

SERVER_HOST

MCP server bind address

0.0.0.0

No

SERVER_PORT

MCP server port

8080

No

MCP_SERVER_NAME

MCP server identifier

kodi-controller

No

LOG_LEVEL

Logging level

INFO

No

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

  • šŸ”¤ Word Matching: Complete word matches vs partial matches

  • ā­ Quality Bonus: Higher quality formats (1080p, BluRay) get bonus points

  • āš ļø Suspicious File Detection: Samples, trailers get penalty points

  • šŸ§  Fuzzy Matching: Works with partial terms like "batman" ā†’ "The Dark Knight"

API Reference

Health Check

GET /health

List Tools

GET /tools

Execute Tool (REST)

POST /tools/{tool_name} Content-Type: application/json { "params": { "param1": "value1", "param2": "value2" } }

MCP Protocol Endpoints

POST / # JSON-RPC MCP protocol GET / # Server-Sent Events stream GET /sse # Additional SSE endpoint

Development

Running Tests

# Test new tools functionality ./demo_smart_search.sh # Test all tools ./demo_new_tools_working.sh # Quick Docker test ./quick_docker_test.sh

Project Structure

kodi-mcp-server/ ā”œā”€ā”€ src/ ā”‚ ā”œā”€ā”€ __init__.py ā”‚ ā”œā”€ā”€ config.py # Configuration management ā”‚ ā”œā”€ā”€ kodi_client.py # Kodi JSON-RPC client ā”‚ ā”œā”€ā”€ server.py # Main server entry point ā”‚ ā”œā”€ā”€ hybrid_server.py # Hybrid REST+MCP server ā”‚ ā””ā”€ā”€ pure_mcp_server.py # Pure MCP protocol server ā”œā”€ā”€ docker-compose.yml # Docker deployment ā”œā”€ā”€ Dockerfile # Container definition ā”œā”€ā”€ requirements.txt # Python dependencies ā”œā”€ā”€ .env.example # Environment template ā””ā”€ā”€ README.md # This file

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Add tests if applicable

  5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

Acknowledgments

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables control of Kodi media center through MCP protocol, supporting playback control, library management, navigation, and smart downloads search with automatic file playback.

  1. Features
    1. Core Kodi Controls
    2. Smart Downloads Management
    3. Protocol Support
  2. Quick Start
    1. Using Docker (Recommended)
    2. Manual Installation
  3. Configuration
    1. Environment Variables
    2. Kodi Setup
  4. Available Tools
    1. Player Control
    2. Navigation
    3. Library Operations
    4. Downloads Management
  5. Usage Examples
    1. With MCP Client (Claude Desktop, n8n)
    2. REST API
    3. MCP JSON-RPC Protocol
  6. Integration
    1. n8n MCP Client
    2. Claude Desktop
  7. Smart Search Algorithm
    1. API Reference
      1. Health Check
      2. List Tools
      3. Execute Tool (REST)
      4. MCP Protocol Endpoints
    2. Development
      1. Running Tests
      2. Project Structure
    3. Contributing
      1. License
        1. Support
          1. Acknowledgments

            New MCP Servers

            MCP directory API

            We provide all the information about MCP servers via our MCP API.

            curl -X GET 'https://glama.ai/api/mcp/v1/servers/laHeud/kodi-mcp-server'

            If you have feedback or need assistance with the MCP directory API, please join our Discord server