stremio-mcp

Servidor MCP en Python para búsqueda en TMDB, gestión de biblioteca de Stremio y reproducción/control de Android TV mediante ADB nativo.

GitHub

Documentación

Servidor MCP de Stremio

Un servidor Python de Model Context Protocol (MCP) para buscar en TMDB, abrir contenido de Stremio en Android TV, controlar la reproducción mediante ADB y, opcionalmente, acceder a tu biblioteca de Stremio.

[!IMPORTANT] Este servidor puede controlar un Android TV físico y, cuando STREMIO_AUTH_KEY está configurado, añadir o eliminar elementos de tu biblioteca de Stremio. ADB otorga un acceso potente al dispositivo. Revisa las solicitudes de herramientas, mantén privadas las credenciales y desactiva la Depuración Inalámbrica cuando no la estés usando.

Qué hace

Busca películas y series en TMDB y devuelve IDs de IMDb.
Abre una película o un episodio específico de una serie en Stremio en Android TV.
Envía comandos de navegación, reproducción, volumen y encendido mediante ADB nativo.
Lee datos de título, estado, posición y duración de la reproducción según el dispositivo.
Opcionalmente, lista, busca, añade y elimina elementos de la biblioteca de Stremio.

Requisitos

Android TV con Stremio instalado y configurado con addons funcionales
Para la Depuración Inalámbrica moderna en TV: Android TV / Google TV con Android 13 (API 33) o superior, según los requisitos de adb inalámbrico de Google
Python 3.10+
uv
Android SDK Platform Tools (adb) — instala una versión actual y mantenla actualizada; usa al menos la era de depuración inalámbrica de Platform Tools (30.0.0+, cuando llegó adb pair). Prefiere la última versión estable de la página de Platform Tools para las correcciones de mDNS y TLS
Una clave de API de TMDB gratuita para la búsqueda de títulos
Opcional: una clave de autenticación de Stremio para el acceso a la biblioteca

Instalación

Paquete PyPI (recomendado)

Ejecuta la última versión publicada sin clonar el repositorio:

uvx stremio-mcp-server

Para ejecutar explícitamente la versión actual:

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

[!NOTE] Este proyecto se publica en PyPI como stremio-mcp-server. Un proyecto separado y no relacionado se publica como stremio-mcp; instalar ese nombre no instala este servidor. El script de consola stremio-mcp que aparece a continuación lo proporciona la distribución stremio-mcp-server.

Clonado del código fuente

Usa un clonado del código fuente para desarrollo o modificaciones locales:

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

Edita .env con el endpoint de tu TV y las claves de API. El archivo está ignorado por Git; nunca lo confirmes.

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

Emparejar y conectar la TV

Este servidor se comunica con la TV mediante el cliente nativo adb de Platform Tools, no una biblioteca ADB pura de Python. Esto es intencional: la Depuración Inalámbrica moderna negocia TLS (STLS) y este proyecto necesita un shell completo para intents, eventos de teclas y diagnósticos de sesión de medios. Los clientes puramente Python que solo hablan ADB heredado sobre TCP no cubren esa ruta.

En la TV, activa Opciones de desarrollador y Depuración inalámbrica. Los nombres de los menús varían según el fabricante. La depuración inalámbrica oficial para TV requiere Android 13+; consulta la guía Conectar un dispositivo por Wi-Fi de Google.

La Depuración Inalámbrica moderna muestra puertos de emparejamiento y conexión separados (a menudo efímeros). Empareja una vez y luego conéctate con el puerto de conexión actual:

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

adb connect TV_IP:CONNECTION_PORT
adb devices -l

Configura ANDROID_TV_PORT con el puerto de conexión, no con el puerto de emparejamiento temporal. El dispositivo debe aparecer como device, no como offline ni unauthorized. Los puertos de Depuración Inalámbrica pueden cambiar después de un reinicio o de alternar la depuración. En versiones más nuevas de Platform Tools y Android, un dispositivo previamente emparejado también puede reconectarse mediante mDNS cuando vuelve a una red de confianza; aun así, configura el puerto de conexión explícito cuando la interfaz muestre uno.

La depuración de red heredada puede usar el puerto 5555 (adb tcpip después de USB); usa ese flujo de trabajo solo cuando tu TV lo documente explícitamente. Prefiere la Depuración Inalámbrica en TVs compatibles.

Configurar tu cliente MCP

Ubicaciones del archivo de configuración de Claude Desktop:

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

Paquete PyPI (recomendado)

Crea un archivo de entorno privado a partir del ejemplo anterior y luego configura:

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

Clonado del código fuente

Reemplaza ambas rutas absolutas:

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

Reinicia el cliente MCP después de cambiar la configuración. También puedes colocar las variables directamente en el objeto env de la configuración del cliente, pero ese archivo debe permanecer privado.

Configuración

Variable	Requerida para	Sensible	Descripción
`ANDROID_TV_HOST`	Herramientas de reproducción y TV	Detalle de red local	Dirección IP del Android TV
`ANDROID_TV_PORT`	Herramientas de reproducción y TV	No	Puerto de conexión ADB actual; por defecto el heredado `5555`
`TMDB_API_KEY`	`search` y `play` basado en títulos con `source="search"`	Sí	Credencial de TMDB. Un token de acceso de lectura v4 se envía como encabezado `Authorization`; una clave v3 heredada no tiene forma de encabezado y se envía como parámetro de consulta
`STREMIO_AUTH_KEY`	`library` y `play` basado en biblioteca	Sí	Token de cuenta usado para lecturas y escrituras de la biblioteca de Stremio; se envía solo en el cuerpo de la solicitud HTTPS
`ADB_PATH`	Opcional	No	Ejecutable ADB nativo; por defecto `adb` en `PATH`

Las funciones se inicializan de forma independiente. Por ejemplo, la búsqueda en TMDB funciona sin conexión a la TV, mientras que la reproducción directa por IMDb no requiere TMDB. Deja STREMIO_AUTH_KEY vacío para desactivar el acceso a la biblioteca.

Límites de red

Cada solicitud HTTP usa un cliente asíncrono compartido con tiempos de espera explícitos, un tamaño de respuesta limitado y un grupo de conexiones limitado, de modo que un servicio lento o inalcanzable no pueda detener otras llamadas de herramientas o controles del dispositivo. Los valores predeterminados son seguros; anúlalos solo cuando un enlace lento los haga demasiado estrictos. Un valor no analizable o fuera de rango se informa por nombre de variable y se reemplaza con el predeterminado.

Variable	Predeterminado	Descripción
`STREMIO_MCP_CONNECT_TIMEOUT`	`5`	Segundos para establecer una conexión
`STREMIO_MCP_READ_TIMEOUT`	`20`	Segundos para esperar datos de respuesta
`STREMIO_MCP_WRITE_TIMEOUT`	`20`	Segundos para enviar datos de solicitud
`STREMIO_MCP_POOL_TIMEOUT`	`5`	Segundos para esperar una conexión del grupo
`STREMIO_MCP_MAX_RESPONSE_BYTES`	`4194304`	Tamaño máximo del cuerpo de respuesta de TMDB/Cinemeta
`STREMIO_MCP_LIBRARY_MAX_RESPONSE_BYTES`	`16777216`	Tamaño máximo del cuerpo de respuesta de la biblioteca de Stremio
`STREMIO_MCP_MAX_CONNECTIONS`	`8`	Máximo de conexiones simultáneas
`STREMIO_MCP_MAX_CONCURRENT_REQUESTS`	`4`	Máximo de solicitudes TMDB simultáneas durante una búsqueda de expansión

Herramientas y efectos

Herramienta	Propósito	Acceso externo y efectos secundarios
`search`	Descubrimiento TMDB de solo lectura para películas/series e IDs de IMDb	Envía solicitudes de solo lectura limitadas a TMDB; nunca cambia la TV ni la cuenta
`play`	Abrir una película o episodio por ID de IMDb directo o por título	Requiere ADB; la búsqueda por título puede consultar TMDB o la biblioteca, abre Stremio e intenta una pulsación de tecla central
`library`	Leer la cuenta o añadir/eliminar elementos explícitos	Requiere la clave de autenticación de Stremio; solo `add` y `remove` persisten cambios en la cuenta
`tv_control`	Enviar comandos de volumen, reproducción, navegación o encendido	Envía comandos al Android TV físico; la reproducción `stop` verifica su postcondición
`playback_status`	Leer la instantánea de reproducción actual de Stremio	Lee solo diagnósticos de sesión de medios, pista de audio, tiempo de actividad y extractor limitados a Stremio

Usa search para el descubrimiento en TMDB y library con action=search para la colección personal de Stremio. Usa play para abrir contenido, tv_control para comandos tipo control remoto y playback_status para inspeccionar lo que realmente se está reproduciendo. Las cinco herramientas devuelven texto plano en lugar de objetos de resultado estructurados.

Las mutaciones de la biblioteca requieren un ID de IMDb explícito y un tipo de contenido. Busca primero cuando un título sea ambiguo; el play basado en títulos usa el primer resultado coincidente en caso contrario. Para búsquedas por título de play, source=search requiere tanto temporada como episodio para series; source=library puede usar un episodio guardado o usar por defecto S1E1. La reproducción directa de series también requiere ambos números. play informa un intent de Android aceptado, no una transmisión verificada ni una acción de tecla central.

Las lecturas de la biblioteca informan de forma distinta los resultados vacíos, no encontrados y no disponibles. Las mutaciones fallan de forma segura: add y remove se abortan sin escribir siempre que la lectura previa fallara, devolviera un elemento cuyo _id no sea exactamente el ID solicitado, devolviera filas duplicadas o no solicitadas, o devolviera un elemento de un tipo de contenido diferente. Volver a añadir y eliminar son mutaciones de cuenta que conservan el estado de visualización; la eliminación es un borrado suave y las escrituras se verifican con una lectura de seguimiento.

search informa una interrupción de TMDB como un error en lugar de "sin resultados". Cuando una búsqueda automática alcanza solo una de las mitades de películas y series, devuelve la mitad que tuvo éxito y añade una nota (partial results — …). tv_control no verifica los efectos ordinarios de las teclas; usa playback_status para una instantánea, cuyo estado stalled significa que una sesión declarada como PLAYING carecía de audio de Stremio en vivo que lo corroborara. No envíes navigate/select a menos que Stremio tenga el foco previsto.

Ejemplos de indicaciones

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.

Consulta los ejemplos de uso para flujos de trabajo precisos a nivel de herramienta y ejemplos más seguros de buscar-y-reproducir.

Verificar la configuración

Prueba un límite a la vez:

adb devices -l — confirma la conexión a la TV.
Pide al cliente MCP que liste las herramientas — debería mostrar las cinco herramientas anteriores.
"Busca Inception" — confirma la clave de TMDB y el acceso a la red.
"Reproduce la película tt1375666" — confirma ADB y el enlace profundo de Stremio.
"Lista mi biblioteca de Stremio" — confirma opcionalmente la clave de autenticación de Stremio.

La herramienta play confirma que Android aceptó el intent de Stremio y luego intenta una pulsación de tecla central; no verifica la pulsación de tecla ni garantiza que un addon haya proporcionado una transmisión. Stremio puede mostrar una lista de fuentes que requiere tv_control o un control remoto físico.

Solución de problemas

La TV está fuera de línea, no autorizada o inalcanzable

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

Confirma que la computadora y la TV están en la misma LAN y que el aislamiento de clientes está desactivado.
Usa el puerto de conexión actual, no el de emparejamiento.
Acepta la solicitud de autorización en la TV.
Si el emparejamiento está obsoleto, olvida la computadora en la TV y vuelve a emparejar.
En macOS, otorga el permiso Red local en Privacidad y seguridad → Red local al binario adb en sí. Un patrón confiable es iniciar el servidor ADB una vez desde una terminal GUI permitida y luego dejar que el servidor MCP y otras herramientas actúen como clientes de localhost de ese servidor existente.
Un fallo informado como local_network_denied significa que el propio servidor MCP llegó a la TV mediante TCP sin procesar mientras adb no pudo, por lo que la red está bien: aplica los dos pasos de macOS anteriores en lugar de depurar el enrutamiento.
No ejecutes adb kill-server ni adb start-server desde herramientas automatizadas: eso puede descartar un servidor permitido y recrearlo bajo un proceso sin el permiso de macOS requerido.

Stremio se abre pero el contenido no se reproduce

Inicia Stremio manualmente una vez e inicia sesión.
Confirma que los addons de Stremio proporcionan transmisiones para el título.
Selecciona una fuente con tv_control o un control remoto físico.
Para la reproducción directa por IMDb o TMDB de una serie, proporciona tanto temporada como episodio; la reproducción desde la biblioteca puede usar su episodio guardado o usar por defecto S1E1.

La búsqueda o el acceso a la biblioteca fallan

Confirma que la clave correspondiente está presente y no tiene comillas ni espacios adicionales.
Reinicia el cliente MCP después de editar .env.
Renueva una clave de Stremio caducada usando la guía de claves de autenticación.

Limitaciones

Solo Android TV; este servidor usa intents de Android y eventos de teclado ADB.
La reproducción depende de los addons de Stremio y puede requerir selección manual de fuente.
La pulsación automática del centro ocurre tras un retraso fijo de 2,5 segundos y puede no alcanzar el control esperado.
Los metadatos de reproducción varían según el dispositivo Android, la versión del sistema operativo y el reproductor activo.
Los puertos de conexión de la depuración inalámbrica moderna pueden cambiar.
El host debe poder alcanzar TMDB, Stremio y el televisor en la red local para sus respectivas funciones.

Notas técnicas

El servidor abre estos deep links de Stremio a través de ADB:

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

El estado de reproducción se limita al bloque de sesión multimedia de Stremio. El playing reclamado se corrobora con un AudioTrack multimedia iniciado para el propietario de la sesión, de modo que los errores de Exo-player o las sesiones obsoletas se informan como stalled en lugar de reproducción saludable. La posición se estima desde el reloj de reproducción monotónico de Android solo mientras la reproducción está activa, y la duración puede recurrir a diagnósticos del extractor multimedia.

La stop de reproducción verifica las postcondiciones (sin reproducción activa de Stremio). Cuando se ignora la detención de la sesión multimedia, el servidor intenta pausa+atrás y, si es necesario, un respaldo acotado de am force-stop com.stremio.one, e informa de fallo si la sesión sigue reproduciendo.

Desarrollo

Las comprobaciones sin credenciales usan mocks y no contactan con TMDB, Stremio ni un dispositivo Android:

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

Consulta CONTRIBUTING.md para el flujo de contribución, CHANGELOG.md para las notas de versión y SECURITY.md para la notificación de vulnerabilidades y las pautas de redacción de credenciales.

server.json son los metadatos publicados en el Registro MCP oficial. La entrada canónica está enlazada en Disponibilidad.

Disponibilidad

Fuentes canónicas de este servidor. Cualquier cosa publicada en otro lugar no se mantiene aquí.

Superficie	Identidad	Enlace
Repositorio fuente	`netixc/stremio-mcp`	https://github.com/netixc/stremio-mcp
Paquete Python	`stremio-mcp-server`	https://pypi.org/project/stremio-mcp-server/
Registro MCP oficial	`io.github.netixc/stremio-mcp`	https://registry.modelcontextprotocol.io/v0.1/servers/io.github.netixc%2Fstremio-mcp/versions/latest
Versión actual	`v0.2.0`	https://github.com/netixc/stremio-mcp/releases/tag/v0.2.0

Seguridad

Trata STREMIO_AUTH_KEY como una contraseña; permite lecturas y escrituras de la biblioteca.
Los fallos de red se registran y devuelven solo como categoría, host y código de estado. Las credenciales configuradas y las cadenas de consulta con secretos se eliminan de cada registro y de cada error que devuelve el servidor, incluidos los tracebacks y los registros de solicitudes HTTP de terceros.
Los fallos de ADB se registran y devuelven solo como una categoría acotada con orientación, como inalcanzable, no autorizado, sin conexión o tiempo de espera; los endpoints del dispositivo, la salida bruta de ADB y las cargas de comandos nunca se registran ni se devuelven.
Trata la autorización de ADB como acceso de control del dispositivo y protege ~/.android/adbkey.
Nunca publiques .env, configuración del cliente MCP, claves de autenticación, IPs de dispositivos ni claves ADB en issues o registros.
Revisa las mutaciones de cuentas y dispositivos antes de aprobarlas en tu cliente MCP.
Desactiva la depuración inalámbrica y revoca las credenciales cuando ya no sean necesarias.

Licencia y aviso legal

Licenciado bajo la Licencia MIT.

Este proyecto no está afiliado ni respaldado por Stremio, TMDB ni Anthropic. No proporciona contenido multimedia ni elude los requisitos de los addons de Stremio. Úsalo solo con dispositivos y cuentas que estés autorizado a controlar.