Stremio MCP Server

A Python Model Context Protocol (MCP) server for searching TMDB, opening Stremio content on Android TV, controlling playback over ADB, and optionally accessing your Stremio library.

[!IMPORTANT] This server can control a physical Android TV and, when STREMIO_AUTH_KEY is configured, add or remove items from your Stremio library. ADB grants powerful device access. Review tool requests, keep credentials private, and disable Wireless Debugging when you are not using it.

What it does

• Searches TMDB for movies and TV shows and returns IMDb IDs.
• Opens a movie or a specific series episode in Stremio on Android TV.
• Sends navigation, playback, volume, and power commands through native ADB.
• Reads device-dependent playback title, state, position, and duration data.
• Optionally lists, searches, adds, and removes Stremio library items.

Requirements

• Android TV with Stremio installed and configured with working addons
• For modern Wireless Debugging on TV: Android TV / Google TV running Android 13 (API 33) or higher, per Google's wireless adb requirements
• Python 3.10+
• uv
• Android SDK Platform Tools (adb) — install a current release and keep it updated; use at least the wireless-debugging era of Platform Tools (30.0.0+, when adb pair landed). Prefer the latest stable from the Platform Tools page for mDNS and TLS fixes
• A free TMDB API key for title search
• Optional: a Stremio auth key for library access

Installation

PyPI package (recommended)

Run the latest published release without cloning the repository:

uvx stremio-mcp-server

To run the current release explicitly:

uvx --from stremio-mcp-server==0.2.0 stremio-mcp-server

[!NOTE] This project is published on PyPI as stremio-mcp-server. A separate, unrelated project is published as stremio-mcp; installing that name does not install this server. The stremio-mcp console script below is provided by the stremio-mcp-server distribution.

Source checkout

Use a source checkout for development or local modifications:

git clone https://github.com/netixc/stremio-mcp.git
cd stremio-mcp
uv sync --locked
cp .env.example .env

Edit .env with your TV endpoint and API keys. The file is ignored by Git; never commit it.

TMDB_API_KEY=your_tmdb_api_key
ANDROID_TV_HOST=192.168.1.100
ANDROID_TV_PORT=37139
STREMIO_AUTH_KEY=
# ADB_PATH=/absolute/path/to/adb

Pair and connect the TV

This server talks to the TV through the native Platform Tools adb client, not a pure-Python ADB library. That is intentional: modern Wireless Debugging negotiates TLS (STLS) and this project needs a full shell for intents, key events, and media-session diagnostics. Pure-Python clients that only speak legacy ADB-over-TCP do not cover that path.

On the TV, enable Developer options and Wireless debugging. Menu names vary by manufacturer. Official wireless debugging for TV requires Android 13+; see Google's Connect to a device over Wi-Fi guide.

Modern Wireless Debugging displays separate pairing and connection ports (often ephemeral). Pair once, then connect with the current connection port:

adb pair TV_IP:PAIRING_PORT
# Enter the temporary pairing code shown on the TV.

adb connect TV_IP:CONNECTION_PORT
adb devices -l

Set ANDROID_TV_PORT to the connection port, not the temporary pairing port. The device must appear as device, not offline or unauthorized. Wireless Debugging ports may change after a reboot or after debugging is toggled. On newer Platform Tools and Android versions, a previously paired device may also reconnect via mDNS when it returns to a trusted network; still configure the explicit connection port when the UI shows one.

Legacy network debugging may use port 5555 (adb tcpip after USB); only use that workflow when your TV explicitly documents it. Prefer Wireless Debugging on supported TVs.

Configure your MCP client

Claude Desktop configuration file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

PyPI package (recommended)

Create a private environment file from the example above, then configure:

{
  "mcpServers": {
    "stremio": {
      "command": "uvx",
      "args": [
        "--env-file",
        "/absolute/path/to/stremio.env",
        "stremio-mcp-server"
      ]
    }
  }
}

Source checkout

Replace both absolute paths:

{
  "mcpServers": {
    "stremio": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/stremio-mcp",
        "run",
        "--env-file",
        "/absolute/path/to/stremio-mcp/.env",
        "stremio-mcp"
      ]
    }
  }
}

Restart the MCP client after changing configuration. You can instead place the variables directly in the client configuration's env object, but that file must remain private.

Configuration

Features initialize independently. For example, TMDB search works without a TV connection, while direct IMDb playback does not require TMDB. Leave STREMIO_AUTH_KEY empty to disable library access.

Network bounds

Every HTTP request uses one shared async client with explicit timeouts, a bounded response size, and a bounded connection pool, so a slow or unreachable service cannot stall other tool calls or device controls. The defaults are safe; override them only when a slow link makes them too tight. An unparsable or out-of-range value is reported by variable name and replaced with the default.

Tools and effects

Use search for TMDB discovery and library with action=search for the personal Stremio collection. Use play to open content, tv_control for remote-like commands, and playback_status to inspect what is actually playing. All five tools return plain text rather than structured result objects.