mcp-beam

Transmita arquivos locais e URLs de mídia para dispositivos Chromecast e DLNA/UPnP na sua LAN.

Documentação

mcp-beam

mcp-beam app icon

Demonstração

mcp-beam demo

mcp-beam é um servidor MCP (transporte stdio) para transmitir arquivos locais e URLs de mídia para dispositivos Chromecast e DLNA/UPnP na sua rede local.

Ele expõe sete ferramentas:

list_local_hardware
beam_media
get_beaming_status
play_beaming
pause_beaming
seek_beaming
stop_beaming

Destaques

Um único servidor para fluxos de trabalho Chromecast e DLNA/UPnP.
IDs de dispositivo estáveis para chamadas de acompanhamento confiáveis.
Decisões de reprodução direta e transcodificação com ciência do protocolo.
Políticas de caminho, URL e bind seguras por padrão.
Erros estruturados com dicas práticas de correção.

Sumário

Demonstração
Início Rápido
Instalação
Dependências de Execução
- Instalação do Go
Referência de Ferramentas
Comportamento de Transcodificação
Modelo de Erros
Variáveis de Ambiente
Segurança
Arquitetura
Solução de Problemas
Desenvolvimento

Início Rápido

Comece a transmitir em poucos minutos.

1) Adicione `mcp-beam` à configuração do seu host MCP

Comandos de uma linha via CLI:

# Claude Code
claude mcp add --scope user mcp-beam -- go run go2tv.app/mcp-beam@latest

# Codex
codex mcp add mcp-beam -- go run go2tv.app/mcp-beam@latest

# Gemini
gemini mcp add mcp-beam go run go2tv.app/mcp-beam@latest

Configuração JSON genérica (para hosts MCP que usam mcpServers):

{
  "mcpServers": {
    "mcp-beam": {
      "command": "go",
      "args": [
        "run",
        "go2tv.app/mcp-beam@latest"
      ]
    }
  }
}

Observações:

Requer go em PATH (Go 1.26+).
A primeira execução pode ser mais lenta devido ao download/compilação do módulo.

2) Verifique o binário do servidor/conexão do módulo

go run go2tv.app/mcp-beam@latest --version
go run go2tv.app/mcp-beam@latest --self-test

3) Execute o fluxo das ferramentas

Chame list_local_hardware e escolha um dispositivo id.
Chame beam_media com source e target_device.
Chame get_beaming_status, play_beaming, pause_beaming ou seek_beaming conforme necessário.
Chame stop_beaming quando terminar.

Exemplo de fluxo mínimo:

{
  "name": "list_local_hardware",
  "arguments": {
    "timeout_ms": 3000,
    "include_unreachable": false
  }
}

{
  "name": "beam_media",
  "arguments": {
    "source": "/absolute/path/to/video.mp4",
    "target_device": "dev_1234abcd",
    "transcode": "auto"
  }
}

{
  "name": "get_beaming_status",
  "arguments": {
    "session_id": "sess_abcd1234"
  }
}

{
  "name": "pause_beaming",
  "arguments": {
    "session_id": "sess_abcd1234"
  }
}

{
  "name": "play_beaming",
  "arguments": {
    "session_id": "sess_abcd1234"
  }
}

{
  "name": "seek_beaming",
  "arguments": {
    "session_id": "sess_abcd1234",
    "mode": "percent",
    "value": 50
  }
}

{
  "name": "stop_beaming",
  "arguments": {
    "session_id": "sess_abcd1234"
  }
}

Instalação

Módulo publicado (recomendado)

go run go2tv.app/mcp-beam@latest --version
go run go2tv.app/mcp-beam@latest --self-test

Checkout local

A partir da raiz do repositório:

go run . --version
go run . --self-test

Use esta configuração MCP para executar diretamente do código-fonte:

macOS/Linux:

{
  "mcpServers": {
    "mcp-beam": {
      "command": "/bin/bash",
      "args": [
        "-lc",
        "cd /absolute/path/to/mcp-beam && go run ."
      ]
    }
  }
}

Windows PowerShell:

{
  "mcpServers": {
    "mcp-beam": {
      "command": "powershell",
      "args": [
        "-NoProfile",
        "-Command",
        "Set-Location 'C:\\absolute\\path\\to\\mcp-beam'; go run ."
      ]
    }
  }
}

Binário baixado

Compile localmente:

go build -o ./bin/mcp-beam .
./bin/mcp-beam --version
./bin/mcp-beam --self-test

Ou instale a partir dos lançamentos:

https://github.com/alexballas/mcp-beam/releases

Verificação de checksum Linux/macOS:

shasum -a 256 -c SHA256SUMS

Verificação de checksum Windows:

Get-FileHash .\mcp-beam_<version>_windows_amd64.zip -Algorithm SHA256

Descompactação Linux/macOS:

tar -xzf mcp-beam_<version>_<os>_<arch>.tar.gz
./mcp-beam_<version>_<os>_<arch>/mcp-beam --version
./mcp-beam_<version>_<os>_<arch>/mcp-beam --self-test

Descompactação Windows:

Expand-Archive .\mcp-beam_<version>_windows_amd64.zip -DestinationPath .
.\mcp-beam_<version>_windows_amd64\mcp-beam.exe --version
.\mcp-beam_<version>_windows_amd64\mcp-beam.exe --self-test

Configuração MCP para um binário local:

{
  "mcpServers": {
    "mcp-beam": {
      "command": "/absolute/path/to/mcp-beam",
      "args": []
    }
  }
}

Dependências de Execução

go (Go 1.26+) é necessário ao usar go run, compilar localmente ou empacotar lançamentos. Consulte Instalação do Go abaixo.
Binários de lançamento baixados não exigem uma instalação local do Go.
ffmpeg e ffprobe são opcionais para caminhos sem transcodificação, mas recomendados.
- Se a transcodificação for necessária e ffmpeg estiver indisponível, as chamadas retornam FFMPEG_NOT_FOUND.

Instalação do Go

Linux

Baixe e instale a partir de https://go.dev/dl/ ou via gerenciador de pacotes:

Debian/Ubuntu: sudo apt install golang-go
Fedora: sudo dnf install golang
Arch: sudo pacman -S go

macOS

Baixe e instale a partir de https://go.dev/dl/ ou use Homebrew:

brew install go

Windows

Baixe e instale a partir de https://go.dev/dl/

Verifique a Instalação

go version

Deve exibir: go1.26.0 ou superior.

Exemplos de instalação:

Linux: gerenciador de pacotes (por exemplo, sudo apt install ffmpeg)
macOS: brew install ffmpeg
Windows: instale o FFmpeg e adicione bin ao PATH

Verifique:

Linux/macOS: command -v ffmpeg && command -v ffprobe
Windows: where ffmpeg e where ffprobe

Referência de Ferramentas

`list_local_hardware`

Descubra renderizadores Chromecast e DLNA/UPnP na rede local.

Argumentos:

timeout_ms (inteiro opcional, mínimo 100, padrão 5000)
include_unreachable (booleano opcional, padrão false)

Exemplo:

{
  "name": "list_local_hardware",
  "arguments": {
    "timeout_ms": 5000,
    "include_unreachable": false
  }
}

Em caso de sucesso, structuredContent inclui:

count
Entradas de devices[]:
id
name
type
address
is_audio_only
protocol (chromecast ou dlna)
capabilities.supports_file_source
capabilities.supports_url_source
capabilities.supports_hls_m3u8_url
capabilities.limitations[]

`beam_media`

Inicie a reprodução em um dispositivo descoberto selecionado.

Argumentos:

source (string obrigatória): caminho absoluto de arquivo local, ou URL http/https
target_device (string obrigatória): ID de dispositivo estável preferido, nome exato como alternativa
transcode (string opcional): auto (padrão), always, never
subtitles_path (string opcional): caminho absoluto do arquivo de legenda local (.srt ou .vtt)
start_seconds (inteiro opcional, mínimo 0): deslocamento inicial a partir do início da mídia

Exemplo:

{
  "name": "beam_media",
  "arguments": {
    "source": "/absolute/path/to/media.mp4",
    "target_device": "dev_1234abcd",
    "transcode": "auto",
    "subtitles_path": "/absolute/path/to/subs.srt",
    "start_seconds": 60
  }
}

Em caso de sucesso, structuredContent inclui:

ok
session_id
device_id
media_url
transcoding
warnings[]

Observações de protocolo:

Chromecast suporta arquivos locais e fontes de URL.
Chromecast suporta transmissão direta de URL HLS .m3u8.
DLNA suporta arquivos locais e fontes de URL com comportamento direto-primeiro e depois fallback de proxy.
URLs .m3u8 do DLNA são rejeitadas com detalhes estruturados de limitação.
Quando subtitles_path é omitido para arquivos locais, o mcp-beam detecta automaticamente legendas laterais usando o mesmo nome base (.srt, depois .vtt).

`get_beaming_status`

Obtenha o status atual de reprodução de uma sessão de transmissão ativa.

Argumentos:

target_device (string opcional)
session_id (string opcional)
Pelo menos um de target_device ou session_id é obrigatório.

Exemplo:

{
  "name": "get_beaming_status",
  "arguments": {
    "session_id": "sess_abcd1234"
  }
}

Em caso de sucesso, structuredContent inclui:

ok
session_id
device_id
device_name
protocol
state
position_seconds opcional
duration_seconds opcional
title opcional
content_type opcional
media_url
transcoding
warnings[]

`play_beaming`

Retome uma sessão de transmissão ativa.

Argumentos:

target_device (string opcional)
session_id (string opcional)
Pelo menos um de target_device ou session_id é obrigatório.

Exemplo:

{
  "name": "play_beaming",
  "arguments": {
    "session_id": "sess_abcd1234"
  }
}

Em caso de sucesso, structuredContent inclui:

ok
session_id
device_id
state (playing)

`pause_beaming`

Pause uma sessão de transmissão ativa.

Argumentos:

target_device (string opcional)
session_id (string opcional)
Pelo menos um de target_device ou session_id é obrigatório.

Exemplo:

{
  "name": "pause_beaming",
  "arguments": {
    "session_id": "sess_abcd1234"
  }
}

Em caso de sucesso, structuredContent inclui:

ok
session_id
device_id
state (paused)

`stop_beaming`

Pare uma sessão de transmissão ativa.

Argumentos:

target_device (string opcional)
session_id (string opcional)
Pelo menos um de target_device ou session_id é obrigatório.

Exemplo:

{
  "name": "stop_beaming",
  "arguments": {
    "session_id": "sess_abcd1234"
  }
}

Em caso de sucesso, structuredContent inclui:

ok
stopped_session_id
device_id
warnings (avisos opcionais de limpeza após a reprodução ser interrompida)

`seek_beaming`

Busque em uma sessão de transmissão ativa por posição absoluta, porcentagem, deslocamento a partir do fim ou delta relativo.

Argumentos:

target_device (string opcional)
session_id (string opcional)
mode (string obrigatória): como interpretar value. Uma de:
absolute_seconds: pular para um timestamp medido a partir do início
percent: pular para uma porcentagem da duração total (0 a 100)
from_end_seconds: pular para um ponto medido de trás para frente a partir do fim
delta_seconds: pular em relação à posição atual; valores negativos retrocedem
value (número obrigatório): o valor da busca, interpretado por mode.
Pelo menos um de target_device ou session_id é obrigatório.

Exemplo:

{
  "name": "seek_beaming",
  "arguments": {
    "session_id": "sess_abcd1234",
    "mode": "from_end_seconds",
    "value": 10
  }
}

Em caso de sucesso, structuredContent inclui:

ok
session_id
device_id
position_seconds
requested_mode
resolved_position_seconds
duration_seconds opcional

Exemplos:

Meio da mídia: mode: percent, value: 50
Dez segundos a partir do fim: mode: from_end_seconds, value: 10
Segundo exato: mode: absolute_seconds, value: 120
Avançar 30 segundos: mode: delta_seconds, value: 30
Retroceder 10 segundos: mode: delta_seconds, value: -10

Observação:

Modos relativos à duração (percent, from_end_seconds) exigem duração de mídia conhecida.

Comportamento de Transcodificação

Valores de beam_media.arguments.transcode:

auto (padrão)
always
never

Resumo do comportamento:

never: não transcodificar.
always: forçar transcodificação para fontes de vídeo; ignorado para fontes que não são de vídeo.
auto: comportamento padrão com ciência do protocolo.
Arquivos locais Chromecast: transcodificar somente quando a compatibilidade de codec exigir.
Fontes de URL Chromecast: fluxo direto por padrão.
Arquivos locais DLNA: transcodificar somente com always para fontes de vídeo.
Fontes de URL DLNA: direto-primeiro e depois fallback de proxy; transcodificação forçada somente com always para vídeo.

Casos de borda:

Valores inválidos de transcode retornam JSON-RPC -32602 (invalid params).
transcode=always com HLS Chromecast direto (URLs .m3u8) é rejeitado.
Se a transcodificação for necessária/solicitada e ffmpeg estiver indisponível, a chamada retorna FFMPEG_NOT_FOUND.
Os resultados incluem structuredContent.transcoding e warnings[] para que os chamadores possam verificar o que foi executado.

Modelo de Erros

Falhas de validação de entrada:

Erro JSON-RPC -32602 (invalid params)

Falhas de ferramentas:

isError=true
structuredContent.error inclui:
code
message
limitations[] opcional
suggested_fixes[] opcional
details opcional

Códigos de erro comuns de ferramentas:

DEVICE_NOT_FOUND
DEVICE_UNREACHABLE
FILE_NOT_FOUND
FILE_NOT_READABLE
UNSUPPORTED_MEDIA
UNSUPPORTED_SOURCE_FOR_PROTOCOL
UNSUPPORTED_URL_PATTERN
TRANSCODE_REQUIRED
FFMPEG_NOT_FOUND
SEEK_MODE_INVALID
SEEK_POSITION_INVALID
SEEK_DURATION_UNKNOWN
PROTOCOL_ERROR
INTERNAL_ERROR

Variáveis de Ambiente

Variável	Padrão	Efeito
`MCP_BEAM_STRICT_PATH_POLICY`	`false`	Ativa a aplicação estrita da lista de permissões de caminhos de arquivo/legenda.
`MCP_BEAM_ALLOWED_PATH_PREFIXES`	vazio	Prefixos absolutos separados por vírgula permitidos no modo estrito.
`MCP_BEAM_ALLOW_LOOPBACK_URLS`	`false`	Permite hosts de URL `localhost`/loopback quando `true`.
`MCP_BEAM_ALLOW_WILDCARD_BIND`	`false`	Permite endereços de bind curinga quando `true`.
`MCP_BEAM_LOG_LEVEL`	`info`	Nível de log do servidor: `debug`, `info`, `warn`, `error`.
`MCP_BEAM_HANDLE_SIGINT`	`false`	Lida com `SIGINT` internamente quando `true`; por padrão, os hosts MCP controlam o tratamento de interrupções.

Segurança

Controles de segurança:

Caminhos de arquivos locais devem ser absolutos.
O modo de caminho estrito aplica prefixos na lista de permissões e rejeita escapes de caminho.
Somente URLs http e https são aceitas.
Hosts de loopback (localhost, 127.0.0.0/8, ::1) são bloqueados por padrão.
Endereços de bind curinga (0.0.0.0, ::) são bloqueados por padrão.
Rotas temporárias de mídia usam tokens aleatórios e impossíveis de adivinhar.
A propriedade da sessão é local ao processo e em memória.

Linha de base de produção recomendada:

Mantenha MCP_BEAM_ALLOW_LOOPBACK_URLS=false a menos que seja explicitamente necessário para testes somente locais.
Mantenha MCP_BEAM_ALLOW_WILDCARD_BIND=false.
Ative MCP_BEAM_STRICT_PATH_POLICY=true com MCP_BEAM_ALLOWED_PATH_PREFIXES explícito.
Execute mcp-beam sob uma conta de sistema operacional com privilégios mínimos. Fronteiras de ameaça:
A entrada do cliente MCP não é confiável e é validada estritamente.
Os hosts de URL de origem são fronteiras de confiança externas.
Os listeners de mídia são visíveis na LAN e devem ser executados apenas em redes confiáveis.
Os endpoints de controle de dispositivos (Chromecast/DLNA) dependem da integridade da LAN.

Arquitetura

MCP Host (MCP client)
        |
        | stdio JSON-RPC (MCP)
        v
  mcp-beam (single process)
  - internal/mcpserver   (initialize, tools/list, tools/call)
  - internal/discovery   (unified DLNA + Chromecast discovery)
  - internal/beam        (session manager + lifecycle + cleanup)
        |
        +--> go2tv castprotocol    (Chromecast control)
        +--> go2tv soapcalls       (DLNA control)
        +--> go2tv httphandlers    (temporary HTTP media serving)
        +--> go2tv utils           (MIME/transcode/url helpers)

Modelo de execução:

Binário único headless.
MCP apenas via stdin/stdout.
O gerenciador de sessões em processo é a fonte da verdade.
Uma sessão ativa por dispositivo de destino.

Fluxo principal:

list_local_hardware: descobrir, normalizar, IDs estáveis, filtro opcional de alcance.
beam_media: validar origem, resolver destino, escolher protocolo, decidir transcodificação, iniciar reprodução, persistir sessão.
get_beaming_status: consultar sessões ativas por session_id ou target_device.
play_beaming / pause_beaming: retomar ou pausar sessões ativas por session_id ou target_device.
seek_beaming: buscar em sessões ativas por session_id ou target_device.
stop_beaming: resolver sessão/dispositivo, interromper reprodução do protocolo, liberar recursos de execução.

Padrões do ciclo de vida da sessão:

idle_cleanup_after = 10m
paused_cleanup_after = 90m
max_session_age = 24h
intervalo de varredura 5s

Fontes de estado:

Chromecast via polling de status (GetStatus)
Monitoramento híbrido DLNA (callbacks + fallback de polling)

Solução de problemas

Diagnóstico rápido:

mcp-beam --version
mcp-beam --self-test

Logs detalhados:

MCP_BEAM_LOG_LEVEL=debug mcp-beam

Problemas comuns:

FFMPEG_NOT_FOUND: instale ffmpeg/ffprobe, depois verifique PATH.
DEVICE_NOT_FOUND: execute list_local_hardware e reutilize o id retornado.
DEVICE_UNREACHABLE: verifique se o destino está ligado e acessível.
UNSUPPORTED_URL_PATTERN: a origem deve ser roteável http/https; apenas para testes de loopback local, defina MCP_BEAM_ALLOW_LOOPBACK_URLS=true.
UNSUPPORTED_SOURCE_FOR_PROTOCOL: Chromecast de destino para .m3u8.
PROTOCOL_ERROR com política de bind: use um endereço de bind LAN concreto; defina MCP_BEAM_ALLOW_WILDCARD_BIND=true apenas em ambientes controlados.
invalid params: remova campos desconhecidos e corresponda exatamente aos nomes/tipos de argumentos.

Problemas de descoberta:

Se nenhum dispositivo for retornado, aumente timeout_ms.
Defina include_unreachable=true para depuração.
Verifique o firewall/acesso de descoberta de rede.

Problemas de inicialização:

Verifique o caminho do comando e as permissões do executável.
No Windows, use o caminho completo para mcp-beam.exe.
Nos logs de depuração, verifique mcp_server_start, mcp_read_wait, mcp_message_received.

Desenvolvimento

Comandos comuns:

make test
make lint
make release
make clean

mcp-beam

Documentação

mcp-beam

Demonstração

Destaques

Sumário

Início Rápido

1) Adicione mcp-beam à configuração do seu host MCP

2) Verifique o binário do servidor/conexão do módulo

3) Execute o fluxo das ferramentas

Instalação

Módulo publicado (recomendado)

Checkout local

Binário baixado

Dependências de Execução

Instalação do Go

Linux

macOS

Windows

Verifique a Instalação

Referência de Ferramentas

list_local_hardware

beam_media

get_beaming_status

play_beaming

pause_beaming

stop_beaming

seek_beaming

Comportamento de Transcodificação

Modelo de Erros

Variáveis de Ambiente

Segurança

Arquitetura

Solução de problemas

Desenvolvimento

1) Adicione `mcp-beam` à configuração do seu host MCP

`list_local_hardware`

`beam_media`

`get_beaming_status`

`play_beaming`

`pause_beaming`

`stop_beaming`

`seek_beaming`