stremio-mcp

Servidor MCP em Python para busca no TMDB, gerenciamento da biblioteca do Stremio e reprodução/controle em Android TV via ADB nativo.

GitHub

Documentação

Servidor MCP Stremio

Um servidor Python Model Context Protocol (MCP) para pesquisar no TMDB, abrir conteúdo do Stremio na Android TV, controlar a reprodução via ADB e, opcionalmente, acessar sua biblioteca do Stremio.

[!IMPORTANT] Este servidor pode controlar uma Android TV física e, quando STREMIO_AUTH_KEY estiver configurado, adicionar ou remover itens da sua biblioteca do Stremio. O ADB concede acesso poderoso ao dispositivo. Revise as solicitações de ferramentas, mantenha as credenciais privadas e desative a Depuração sem fio quando não estiver em uso.

O que ele faz

Pesquisa filmes e séries de TV no TMDB e retorna IDs do IMDb.
Abre um filme ou um episódio específico de série no Stremio na Android TV.
Envia comandos de navegação, reprodução, volume e energia via ADB nativo.
Lê dados de título, estado, posição e duração da reprodução dependentes do dispositivo.
Opcionalmente, lista, pesquisa, adiciona e remove itens da biblioteca do Stremio.

Requisitos

Android TV com Stremio instalado e configurado com addons funcionais
Para Depuração sem fio moderna na TV: Android TV / Google TV com Android 13 (API 33) ou superior, conforme os requisitos de adb sem fio do Google
Python 3.10+
uv
Android SDK Platform Tools (adb) — instale uma versão atual e mantenha-a atualizada; use pelo menos a era de depuração sem fio das Platform Tools (30.0.0+, quando adb pair foi introduzido). Prefira a versão estável mais recente da página das Platform Tools para correções de mDNS e TLS
Uma chave de API TMDB gratuita para pesquisa de títulos
Opcional: uma chave de autenticação Stremio para acesso à biblioteca

Instalação

Pacote PyPI (recomendado)

Execute a versão publicada mais recente sem clonar o repositório:

uvx stremio-mcp-server

Para executar a versão atual explicitamente:

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

[!NOTE] Este projeto é publicado no PyPI como stremio-mcp-server. Um projeto separado e não relacionado é publicado como stremio-mcp; instalar esse nome não instala este servidor. O script de console stremio-mcp abaixo é fornecido pela distribuição stremio-mcp-server.

Checkout do código-fonte

Use um checkout do código-fonte para desenvolvimento ou modificações locais:

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

Edite .env com o endpoint da sua TV e as chaves de API. O arquivo é ignorado pelo Git; nunca o envie para o repositório.

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

Parear e conectar a TV

Este servidor se comunica com a TV por meio do cliente nativo adb das Platform Tools, não uma biblioteca ADB puramente em Python. Isso é intencional: a Depuração sem fio moderna negocia TLS (STLS) e este projeto precisa de um shell completo para intents, eventos de tecla e diagnósticos de sessão de mídia. Clientes puramente em Python que apenas falam ADB-legado sobre TCP não cobrem esse caminho.

Na TV, ative Opções do desenvolvedor e Depuração sem fio. Os nomes dos menus variam conforme o fabricante. A depuração sem fio oficial para TV requer Android 13+; consulte o guia Conectar a um dispositivo via Wi-Fi do Google.

A Depuração sem fio moderna exibe portas separadas de pareamento e conexão (frequentemente efêmeras). Pareie uma vez e depois conecte com a porta de conexão atual:

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

adb connect TV_IP:CONNECTION_PORT
adb devices -l

Defina ANDROID_TV_PORT para a porta de conexão, não a porta temporária de pareamento. O dispositivo deve aparecer como device, não offline ou unauthorized. As portas da Depuração sem fio podem mudar após uma reinicialização ou após alternar a depuração. Em versões mais novas das Platform Tools e do Android, um dispositivo previamente pareado também pode se reconectar via mDNS quando retornar a uma rede confiável; ainda assim, configure a porta de conexão explícita quando a interface mostrar uma.

A depuração de rede legada pode usar a porta 5555 (adb tcpip após USB); use esse fluxo de trabalho apenas quando sua TV o documentar explicitamente. Prefira a Depuração sem fio em TVs compatíveis.

Configure seu cliente MCP

Locais do arquivo de configuração do 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

Pacote PyPI (recomendado)

Crie um arquivo de ambiente privado a partir do exemplo acima e configure:

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

Checkout do código-fonte

Substitua ambos os caminhos absolutos:

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

Reinicie o cliente MCP após alterar a configuração. Você pode, em vez disso, colocar as variáveis diretamente no objeto env da configuração do cliente, mas esse arquivo deve permanecer privado.

Configuração

Variável	Necessária para	Sensível	Descrição
`ANDROID_TV_HOST`	Ferramentas de reprodução e TV	Detalhe de rede local	Endereço IP da Android TV
`ANDROID_TV_PORT`	Ferramentas de reprodução e TV	Não	Porta de conexão ADB atual; padrão é a legada `5555`
`TMDB_API_KEY`	`search` e `play` baseada em título com `source="search"`	Sim	Credencial do TMDB. Um token de acesso de leitura v4 é enviado como cabeçalho `Authorization`; uma chave v3 legada não tem forma de cabeçalho e é enviada como parâmetro de consulta
`STREMIO_AUTH_KEY`	`library` e `play` baseada em biblioteca	Sim	Token de conta usado para leituras e gravações da biblioteca do Stremio; enviado apenas no corpo da solicitação HTTPS
`ADB_PATH`	Opcional	Não	Executável ADB nativo; padrão é `adb` em `PATH`

Os recursos são inicializados de forma independente. Por exemplo, a pesquisa no TMDB funciona sem conexão com a TV, enquanto a reprodução direta por IMDb não requer TMDB. Deixe STREMIO_AUTH_KEY vazio para desativar o acesso à biblioteca.

Limites de rede

Cada solicitação HTTP usa um cliente assíncrono compartilhado com timeouts explícitos, um tamanho de resposta limitado e um pool de conexões limitado, de modo que um serviço lento ou inacessível não pode travar outras chamadas de ferramentas ou controles do dispositivo. Os padrões são seguros; substitua-os apenas quando um link lento os tornar muito restritos. Um valor não analisável ou fora do intervalo é relatado pelo nome da variável e substituído pelo padrão.

Variável	Padrão	Descrição
`STREMIO_MCP_CONNECT_TIMEOUT`	`5`	Segundos para estabelecer uma conexão
`STREMIO_MCP_READ_TIMEOUT`	`20`	Segundos para aguardar dados de resposta
`STREMIO_MCP_WRITE_TIMEOUT`	`20`	Segundos para enviar dados de solicitação
`STREMIO_MCP_POOL_TIMEOUT`	`5`	Segundos para aguardar uma conexão do pool
`STREMIO_MCP_MAX_RESPONSE_BYTES`	`4194304`	Tamanho máximo do corpo de resposta TMDB/Cinemeta
`STREMIO_MCP_LIBRARY_MAX_RESPONSE_BYTES`	`16777216`	Tamanho máximo do corpo de resposta da biblioteca do Stremio
`STREMIO_MCP_MAX_CONNECTIONS`	`8`	Máximo de conexões simultâneas
`STREMIO_MCP_MAX_CONCURRENT_REQUESTS`	`4`	Máximo de solicitações TMDB simultâneas durante uma pesquisa fan-out

Ferramentas e efeitos

Ferramenta	Finalidade	Acesso externo e efeitos colaterais
`search`	Descoberta TMDB somente leitura para filmes/TV e IDs IMDb	Envia solicitações somente leitura limitadas ao TMDB; nunca altera a TV ou a conta
`play`	Abrir um filme ou episódio por ID IMDb direto ou por título	Requer ADB; a pesquisa por título pode consultar o TMDB ou a biblioteca, abre o Stremio e tenta pressionar a tecla central
`library`	Ler a conta ou adicionar/remover itens explícitos	Requer a chave de autenticação do Stremio; apenas `add` e `remove` persistem alterações na conta
`tv_control`	Enviar comandos de volume, reprodução, navegação ou energia	Envia comandos para a Android TV física; a reprodução `stop` verifica sua pós-condição
`playback_status`	Ler o snapshot atual de reprodução do Stremio	Lê apenas diagnósticos de sessão de mídia, faixa de áudio, tempo de atividade e extrator com escopo do Stremio

Use search para descoberta no TMDB e library com action=search para a coleção pessoal do Stremio. Use play para abrir conteúdo, tv_control para comandos semelhantes a controle remoto e playback_status para inspecionar o que está realmente em reprodução. Todas as cinco ferramentas retornam texto simples em vez de objetos de resultado estruturados.

Mutações na biblioteca exigem um ID IMDb explícito e tipo de conteúdo. Pesquise primeiro quando um título for ambíguo; play baseada em título usa o primeiro resultado correspondente. Para pesquisas de título play, source=search exige temporada e episódio para TV; source=library pode usar um episódio salvo ou usar o padrão S1E1. A reprodução direta de séries também exige ambos os números. play relata um intent Android aceito, não um stream verificado ou ação de tecla central.

As leituras da biblioteca relatam resultados vazios, não encontrados e indisponíveis de forma distinta. As mutações falham de forma segura: add e remove abortam sem gravar sempre que a leitura anterior falhou, retornou um item cujo _id não é exatamente o ID solicitado, retornou linhas duplicadas ou não solicitadas, ou retornou um item de tipo de conteúdo diferente. Re-adicionar e remover são mutações de conta que preservam o estado de exibição; a remoção é uma exclusão suave e as gravações são verificadas com uma leitura de acompanhamento.

search relata uma indisponibilidade do TMDB como erro em vez de "sem resultados". Quando uma pesquisa automática atinge apenas uma das metades de filme e TV, ela retorna a metade que teve sucesso e anexa uma nota (partial results — …). tv_control não verifica efeitos comuns de tecla; use playback_status para um snapshot, cujo estado stalled significa que uma sessão declarada como PLAYING não tinha áudio Stremio ao vivo corroborante. Não envie navigate/select a menos que o Stremio tenha o foco pretendido.

Exemplos de prompts

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.

Consulte os exemplos de uso para fluxos de trabalho precisos no nível de ferramenta e exemplos mais seguros de pesquisar-e-reproduzir.

Verifique a configuração

Teste um limite por vez:

adb devices -l — confirma a conexão com a TV.
Peça ao cliente MCP para listar as ferramentas — deve mostrar as cinco ferramentas acima.
"Pesquise por Inception" — confirma a chave TMDB e o acesso à rede.
"Reproduza o filme tt1375666" — confirma o deep linking do ADB e do Stremio.
"Liste minha biblioteca do Stremio" — confirma opcionalmente a chave de autenticação do Stremio.

A ferramenta play confirma que o Android aceitou o intent do Stremio e tenta pressionar a tecla central; ela não verifica o pressionamento da tecla nem garante que um addon forneceu um stream. O Stremio pode mostrar uma lista de fontes que exige tv_control ou um controle remoto físico.

Solução de problemas

TV offline, não autorizada ou inacessível

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

Confirme que o computador e a TV estão na mesma LAN e que o isolamento de cliente está desativado.
Use a porta de conexão atual, não a porta de pareamento.
Aceite o prompt de autorização na TV.
Se o pareamento estiver desatualizado, esqueça o computador na TV e pareie novamente.
No macOS, conceda a permissão Rede Local em Privacidade e Segurança → Rede Local ao binário adb em si. Um padrão confiável é iniciar o servidor ADB uma vez a partir de um terminal GUI permitido e depois deixar o servidor MCP e outras ferramentas atuarem como clientes localhost desse servidor existente.
Uma falha relatada como local_network_denied significa que o próprio servidor MCP alcançou a TV via TCP bruto enquanto adb não conseguiu, então a rede está ok: aplique as duas etapas do macOS acima em vez de depurar o roteamento.
Não execute adb kill-server ou adb start-server a partir de ferramentas automatizadas: isso pode descartar um servidor permitido e recriá-lo sob um processo sem a permissão necessária do macOS.

O Stremio abre, mas o conteúdo não reproduz

Inicie o Stremio manualmente uma vez e faça login.
Confirme que os addons do seu Stremio fornecem streams para o título.
Selecione uma fonte com tv_control ou um controle remoto físico.
Para reprodução direta por título IMDb ou TMDB de uma série, forneça temporada e episódio; a reprodução pela biblioteca pode usar o episódio salvo ou o padrão S1E1.

A pesquisa ou o acesso à biblioteca falha

Confirme que a chave relevante está presente e não possui aspas ou espaços extras.
Reinicie o cliente MCP após editar .env.
Renove uma chave Stremio expirada usando o guia de chave de autenticação.

Limitações

Apenas Android TV; este servidor usa intents do Android e eventos de tecla ADB.
A reprodução depende dos addons do Stremio e pode exigir seleção manual de fonte.
O pressionamento automático do centro ocorre após um atraso fixo de 2,5 segundos e pode não acertar o controle esperado.
Os metadados de reprodução variam conforme o dispositivo Android, a versão do SO e o player ativo.
As portas de conexão do Wireless Debugging moderno podem mudar.
O host deve alcançar TMDB, Stremio e a TV na rede local para seus respectivos recursos.

Notas técnicas

O servidor abre estes deep links do Stremio por meio do ADB:

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

O status de reprodução é limitado ao bloco de sessão de mídia do Stremio. O playing reivindicado é corroborado com um AudioTrack de mídia iniciado para o proprietário da sessão, de modo que erros do Exo-player / sessões obsoletas sejam relatados como stalled em vez de reprodução saudável. A posição é estimada a partir do relógio de reprodução monotônico do Android apenas enquanto a reprodução está ativa, e a duração pode recorrer a diagnósticos do extrator de mídia.

A stop de reprodução verifica pós-condições (nenhuma reprodução ativa do Stremio). Quando a interrupção da sessão de mídia é ignorada, o servidor tenta pausa+voltar e, se necessário, um fallback limitado de am force-stop com.stremio.one, e relata falha se a sessão ainda estiver reproduzindo.

Desenvolvimento

As verificações sem credenciais usam mocks e não contatam TMDB, Stremio ou um 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

Consulte CONTRIBUTING.md para o fluxo de contribuição, CHANGELOG.md para notas de versão e SECURITY.md para orientações sobre relato de vulnerabilidades e redação de credenciais.

server.json são os metadados publicados no Registro MCP oficial. A entrada canônica está vinculada em Disponibilidade.

Disponibilidade

Fontes canônicas para este servidor. Qualquer coisa publicada em outro lugar não é mantida aqui.

Superfície	Identidade	Link
Repositório de origem	`netixc/stremio-mcp`	https://github.com/netixc/stremio-mcp
Pacote 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
Versão atual	`v0.2.0`	https://github.com/netixc/stremio-mcp/releases/tag/v0.2.0

Segurança

Trate STREMIO_AUTH_KEY como uma senha; ele permite leituras e gravações na biblioteca.
Falhas de rede são registradas e retornadas apenas como categoria, host e código de status. Credenciais configuradas e strings de consulta com segredos são removidas de todo registro de log e de todo erro retornado pelo servidor, incluindo tracebacks e logs de requisições HTTP de terceiros.
Falhas do ADB são registradas e retornadas como uma categoria limitada apenas com orientação, como inacessível, não autorizado, offline ou timeout; endpoints de dispositivo, saída bruta do ADB e payloads de comando nunca são registrados ou retornados.
Trate a autorização do ADB como acesso de controle do dispositivo e proteja ~/.android/adbkey.
Nunca publique .env, configuração do cliente MCP, chaves de autenticação, IPs de dispositivos ou chaves ADB em issues ou logs.
Revise mutações de conta e dispositivo antes de aprová-las no seu cliente MCP.
Desative o Wireless Debugging e revogue as credenciais quando não forem mais necessárias.

Licença e aviso legal

Licenciado sob a Licença MIT.

Este projeto não é afiliado nem endossado por Stremio, TMDB ou Anthropic. Ele não fornece mídia nem contorna os requisitos de addons do Stremio. Use-o apenas com dispositivos e contas que você está autorizado a controlar.