stremio-mcp

by netixc

Not rated
GitHub

About

Python MCP server for TMDB search, Stremio library management, and Android TV playback/control over native ADB.

Details

Author
netixc
Categories
Productivity, Other, Developer Tools, Search, Knowledge Base

Setup

Install stremio-mcp in your MCP client (Claude Desktop, Cursor, Windsurf, and others).

Repository: https://github.com/netixc/stremio-mcp

Follow the installation instructions in the repository README, then restart your MCP client.

A PythonModel 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, whenSTREMIO_AUTH_KEYis 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.

- 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.

- Android TV withStremioinstalled 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 acurrent releaseand keep it updated; use at least the wireless-debugging era of Platform Tools (30.0.0+, whenadb pairlanded). Prefer the latest stable from the Platform Tools page for mDNS and TLS fixes
- A free
TMDB API keyfor title search
- Optional: a
Stremio auth keyfor library access

Run the latest published release without cloning the repository:

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

[!NOTE] This project is published on PyPI asstremio-mcp-server. A separate, unrelated project is published asstremio-mcp; installing that name does not install this server. Thestremio-mcpconsole script below is provided by thestremio-mcp-serverdistribution.

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.envwith 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

This server talks to the TV through thenative Platform Toolsadbclient, 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, enableDeveloper optionsandWireless debugging. Menu names vary by manufacturer. Official wireless debugging for TV requiresAndroid 13+; see Google'sConnect to a device over Wi-Figuide.

Modern Wireless Debugging displaysseparate 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

SetANDROID_TV_PORTto theconnection port, not the temporary pairing port. The device must appear asdevice, notofflineorunauthorized. 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 port5555(adb tcpipafter USB); only use that workflow when your TV explicitly documents it. Prefer Wireless Debugging on supported TVs.

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

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" ] } } }
{ "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'senvobject, but that file must remain private.

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

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.

Usesearchfor TMDB discovery andlibrarywithaction=searchfor the personal Stremio collection. Useplayto open content,tv_controlfor remote-like commands, andplayback_statusto inspect what is actually playing. All five tools return plain text rather than structured result objects.

Library mutations require an explicit IMDb ID and content type. Search first when a title is ambiguous; title-basedplayotherwise uses the first matching result. Forplaytitle searches,source=searchrequires both season and episode for TV;source=librarycan use a saved episode or default to S1E1. Direct series playback also requires both numbers.playreports an accepted Android intent, not a verified stream or center-key action.

Library reads report empty, not found, and unavailable outcomes distinctly. Mutations fail closed:addandremoveabort without writing whenever the preceding read failed, returned an item whose_idis not exactly the requested ID, returned duplicate or unrequested rows, or returned an item of a different content type. Re-adding and removing are account mutations that preserve watch state; removal is a soft delete and writes are verified with a follow-up read.

searchreports a TMDB outage as an error rather than as "no results". When an automatic search reaches only one of the movie and TV halves, it returns the half that succeeded and appends a(partial results — …)note.tv_controldoes not verify ordinary key effects; useplayback_statusfor a snapshot, whosestalledstate means a claimed PLAYING session lacked corroborating live Stremio audio. Do not sendnavigate/selectunless Stremio has the intended focus.

Search for Dune movies from 2021. Play movie tt1375666. Play Breaking Bad season 1 episode 1. Pause playback. What's currently playing? Search my Stremio library for Severance. Add movie tt1375666 to my library.

See theusage examplesfor accurate tool-level workflows and safer search-then-play examples.
- adb devices -l— confirms the TV connection.
- Ask the MCP client to list tools — should show the five tools above.
- “Search for Inception” — confirms the TMDB key and network access.
- “Play moviett1375666” — confirms ADB and Stremio deep linking.
- “List my Stremio library” — optionally confirms the Stremio auth key.

Theplaytool confirms that Android accepted the Stremio intent, then attempts a center key press; it does not verify the key press or guarantee that an addon supplied a stream. Stremio may show a source list that requirestv_controlor a physical remote.

TV is offline, unauthorized, or unreachable

adb disconnect TV_IP:CONNECTION_PORT adb connect TV_IP:CONNECTION_PORT adb devices -l

- Confirm the computer and TV are on the same LAN and client isolation is disabled.
- Use the current connection port, not the pairing port.
- Accept the authorization prompt on the TV.
- If pairing is stale, forget the computer on the TV and pair again.
- On macOS, grantLocal Networkpermission underPrivacy & Security → Local Networkto theadbbinary itself. A reliable pattern is to start the ADB server once from a permitted GUI terminal, then let the MCP server and other tools act as localhost clients of that existing server.
- A failure reported aslocal_network_deniedmeans the MCP server itself reached the TV over raw TCP whileadbcould not, so the network is fine: apply the two macOS steps above instead of debugging routing.
- Do not runadb kill-serveroradb start-serverfrom automated tooling: that can discard a permitted server and recreate it under a process without the required macOS permission.

- Confirm the relevant key is present and has no quotes or extra spaces.
- Restart the MCP client after editing.env.
- Renew an expired Stremio key using the
auth-key guide.

- Android TV only; this server uses Android intents and ADB key events.
- Playback depends on Stremio addons and may require manual source selection.
- The automatic center press occurs after a fixed 2.5-second delay and may miss the expected control.
- Playback metadata varies by Android device, OS version, and active player.
- Modern Wireless Debugging connection ports can change.
- The host must reach TMDB, Stremio, and the TV on the local network for their respective features.

The server opens these Stremio deep links through ADB:

Movie: stremio:///detail/movie/{imdb_id}/{imdb_id} Series: stremio:///detail/series/{imdb_id}/{imdb_id}:{season}:{episode}

Playback status is scoped to Stremio's media-session block. Claimedplayingis corroborated with a started mediaAudioTrackfor the session owner so Exo-player error / stale sessions are reported asstalledinstead of healthy playback. Position is estimated from Android's monotonic playback clock only while playback is live, and duration may fall back to media-extractor diagnostics.

Playbackstopverifies post-conditions (no active Stremio playback). When media-session stop is ignored, the server tries pause+back and, if needed, a boundedam force-stop com.stremio.onefallback, and reports failure if the session still plays.

Credential-free checks use mocks and do not contact TMDB, Stremio, or an Android device:

uv sync --locked uv run --locked python -m unittest discover -s tests -v uv run --locked python -m compileall -q src tests uv build

SeeCONTRIBUTING.mdfor the contribution workflow,CHANGELOG.mdfor release notes, andSECURITY.mdfor vulnerability reporting and credential-redaction guidance.

server.jsonis the metadata published to the official MCP Registry. The canonical entry is linked inAvailability.

Canonical sources for this server. Anything published elsewhere is not maintained here.

- TreatSTREMIO_AUTH_KEYlike a password; it permits library reads and writes.
- Network failures are logged and returned as a category, host, and status code only. Configured credentials and secret-bearing query strings are stripped from every log record and every error the server returns, including tracebacks and third-party HTTP request logs.
- ADB failures are logged and returned as a bounded category with guidance only, such as unreachable, unauthorized, offline, or timeout; device endpoints, raw ADB output, and command payloads are never logged or returned.
- Treat ADB authorization as device-control access and protect~/.android/adbkey.
- Never post.env, MCP client configuration, auth keys, device IPs, or ADB keys in issues or logs.
- Review account and device mutations before approving them in your MCP client.
- Disable Wireless Debugging and revoke credentials when they are no longer needed.

This project is not affiliated with or endorsed by Stremio, TMDB, or Anthropic. It does not provide media or bypass Stremio addon requirements. Use it only with devices and accounts you are authorized to control.

App Store competitive research for indie iOS developers — ranked keyword search, competitor download and revenue estimates, and iOS In-App Event copy. Free, no API key.

JobYap aggregates job postings directly from companies' official careers sites and gives every posting a public discussion thread, with salaries, locations and full descriptions.

Japanese government procurement bid search and AI analysis via MCP

Prompt Buddy MCP exposes a public, searchable catalog of reusable AI skills.

AI job search & hiring MCP server with 55 tools. Search jobs, apply, interview, negotiate offers across 20 countries. No account needed to start.

Power up your AI agents with 31 production-ready tools. Features local-first Python analysis, real-time SearXNG search, and a secure local proxy to sanitize prompts. Built for developers who value performance and privacy. Install once, use everywhere.

Interact with Amazon services for product search, cart management, and viewing order history.

An MCP server that equips your AI coding assistant with live, verified Android knowledge — so it builds from official sources, not from memory.

MCP server for Apple Notes with semantic search and CRUD operations. Claude searches, reads, creates, updates, and manages your Apple Notes through natural language.

arXiv paper search and full-text reading

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.