mcp-beam

Transmite archivos locales y URLs de medios a dispositivos Chromecast y DLNA/UPnP en tu LAN.

Documentación

mcp-beam

mcp-beam app icon

Demo

mcp-beam demo

mcp-beam es un servidor MCP (transporte stdio) para transmitir archivos locales y URLs de medios a dispositivos Chromecast y DLNA/UPnP en tu red local.

Expone siete herramientas:

list_local_hardware
beam_media
get_beaming_status
play_beaming
pause_beaming
seek_beaming
stop_beaming

Características destacadas

Un solo servidor para flujos de trabajo Chromecast y DLNA/UPnP.
IDs de dispositivo estables para llamadas de seguimiento confiables.
Decisiones de reproducción directa y transcodificación conscientes del protocolo.
Políticas de rutas, URLs y enlaces seguras por defecto.
Errores estructurados con sugerencias prácticas de solución.

Tabla de Contenidos

Demo
Inicio Rápido
Instalación
Dependencias de Ejecución
- Instalación de Go
Referencia de Herramientas
Comportamiento de Transcodificación
Modelo de Errores
Variables de Entorno
Seguridad
Arquitectura
Solución de Problemas
Desarrollo

Inicio Rápido

Comienza a transmitir en pocos minutos.

1) Agrega `mcp-beam` a la configuración de tu host MCP

Comandos de una línea:

# 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

Configuración JSON genérica (para hosts MCP que usan mcpServers):

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

Notas:

Requiere go en PATH (Go 1.26+).
La primera ejecución puede ser más lenta debido a la descarga/compilación de módulos.

2) Verifica el binario del servidor/la conexión del módulo

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

3) Ejecuta el flujo de herramientas

Llama a list_local_hardware y elige un dispositivo id.
Llama a beam_media con source y target_device.
Llama a get_beaming_status, play_beaming, pause_beaming o seek_beaming según sea necesario.
Llama a stop_beaming cuando termines.

Ejemplo de flujo 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"
  }
}

Instalación

Módulo publicado (recomendado)

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

Copia local

Desde la raíz del repositorio:

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

Usa esta configuración MCP para ejecutar directamente desde el código fuente:

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 ."
      ]
    }
  }
}

Binario descargado

Compila localmente:

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

O instala desde los lanzamientos:

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

Verificación de suma de verificación Linux/macOS:

shasum -a 256 -c SHA256SUMS

Verificación de suma de verificación Windows:

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

Desempaquetado 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

Desempaquetado 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

Configuración MCP para un binario local:

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

Dependencias de Ejecución

go (Go 1.26+) es necesario cuando se usa go run, se compila localmente o se empaquetan lanzamientos. Consulta Instalación de Go a continuación.
Los binarios de lanzamiento descargados no requieren una instalación local de Go.
ffmpeg y ffprobe son opcionales para rutas sin transcodificación, pero recomendados.
- Si se requiere transcodificación y ffmpeg no está disponible, las llamadas devuelven FFMPEG_NOT_FOUND.

Instalación de Go

Linux

Descarga e instala desde https://go.dev/dl/ o mediante el gestor de paquetes:

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

macOS

Descarga e instala desde https://go.dev/dl/ o usa Homebrew:

brew install go

Windows

Descarga e instala desde https://go.dev/dl/

Verificar Instalación

go version

Debería mostrar: go1.26.0 o superior.

Ejemplos de instalación:

Linux: gestor de paquetes (por ejemplo sudo apt install ffmpeg)
macOS: brew install ffmpeg
Windows: instala FFmpeg y agrega bin a PATH

Verificar:

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

Referencia de Herramientas

`list_local_hardware`

Descubre renderizadores Chromecast y DLNA/UPnP en la red local.

Argumentos:

timeout_ms (entero opcional, mínimo 100, predeterminado 5000)
include_unreachable (booleano opcional, predeterminado false)

Ejemplo:

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

En caso de éxito, structuredContent incluye:

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

`beam_media`

Inicia la reproducción en un dispositivo descubierto seleccionado.

Argumentos:

source (cadena requerida): ruta de archivo local absoluta, o URL http/https
target_device (cadena requerida): ID de dispositivo estable preferido, nombre exacto como respaldo
transcode (cadena opcional): auto (predeterminado), always, never
subtitles_path (cadena opcional): ruta de archivo de subtítulos local absoluta (.srt o .vtt)
start_seconds (entero opcional, mínimo 0): desplazamiento de inicio desde el comienzo del medio

Ejemplo:

{
  "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
  }
}

En caso de éxito, structuredContent incluye:

ok
session_id
device_id
media_url
transcoding
warnings[]

Notas de protocolo:

Chromecast admite archivos locales y fuentes URL.
Chromecast admite la transmisión directa de URLs HLS .m3u8.
DLNA admite archivos locales y fuentes URL con comportamiento de directo primero y luego respaldo de proxy.
Las URLs .m3u8 de DLNA se rechazan con detalles de limitación estructurados.
Cuando se omite subtitles_path para archivos locales, mcp-beam detecta automáticamente subtítulos laterales usando el mismo nombre base (.srt, luego .vtt).

`get_beaming_status`

Obtiene el estado de reproducción actual de una sesión de transmisión activa.

Argumentos:

target_device (cadena opcional)
session_id (cadena opcional)
Se requiere al menos uno de target_device o session_id.

Ejemplo:

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

En caso de éxito, structuredContent incluye:

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`

Reanuda una sesión de transmisión activa.

Argumentos:

target_device (cadena opcional)
session_id (cadena opcional)
Se requiere al menos uno de target_device o session_id.

Ejemplo:

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

En caso de éxito, structuredContent incluye:

ok
session_id
device_id
state (playing)

`pause_beaming`

Pausa una sesión de transmisión activa.

Argumentos:

target_device (cadena opcional)
session_id (cadena opcional)
Se requiere al menos uno de target_device o session_id.

Ejemplo:

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

En caso de éxito, structuredContent incluye:

ok
session_id
device_id
state (paused)

`stop_beaming`

Detiene una sesión de transmisión activa.

Argumentos:

target_device (cadena opcional)
session_id (cadena opcional)
Se requiere al menos uno de target_device o session_id.

Ejemplo:

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

En caso de éxito, structuredContent incluye:

ok
stopped_session_id
device_id
warnings (advertencias de limpieza opcionales después de detener la reproducción)

`seek_beaming`

Busca en una sesión de transmisión activa por posición absoluta, porcentaje, desplazamiento desde el final o delta relativo.

Argumentos:

target_device (cadena opcional)
session_id (cadena opcional)
mode (cadena requerida): cómo interpretar value. Uno de:
absolute_seconds: saltar a una marca de tiempo medida desde el inicio
percent: saltar a un porcentaje de la duración total (0 a 100)
from_end_seconds: saltar a un punto medido hacia atrás desde el final
delta_seconds: saltar relativo a la posición actual; los valores negativos retroceden
value (número requerido): la cantidad de búsqueda, interpretada por mode.
Se requiere al menos uno de target_device o session_id.

Ejemplo:

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

En caso de éxito, structuredContent incluye:

ok
session_id
device_id
position_seconds
requested_mode
resolved_position_seconds
duration_seconds opcional

Ejemplos:

Mitad del medio: mode: percent, value: 50
Diez segundos desde el final: mode: from_end_seconds, value: 10
Segundo exacto: mode: absolute_seconds, value: 120
Adelantar 30 segundos: mode: delta_seconds, value: 30
Retroceder 10 segundos: mode: delta_seconds, value: -10

Nota:

Los modos relativos a la duración (percent, from_end_seconds) requieren una duración de medio conocida.

Comportamiento de Transcodificación

Valores de beam_media.arguments.transcode:

auto (predeterminado)
always
never

Resumen de comportamiento:

never: no transcodificar.
always: forzar transcodificación para fuentes de video; ignorado para fuentes que no son video.
auto: comportamiento predeterminado consciente del protocolo.
Archivos locales de Chromecast: transcodificar solo cuando la compatibilidad de códec lo requiera.
Fuentes URL de Chromecast: transmisión directa por defecto.
Archivos locales de DLNA: transcodificar solo con always para fuentes de video.
Fuentes URL de DLNA: directo primero y luego respaldo de proxy; transcodificación forzada solo con always para video.

Casos límite:

Los valores inválidos de transcode devuelven JSON-RPC -32602 (invalid params).
transcode=always con HLS directo de Chromecast (URLs .m3u8) se rechaza.
Si se requiere/solicita transcodificación y ffmpeg no está disponible, la llamada devuelve FFMPEG_NOT_FOUND.
Los resultados incluyen structuredContent.transcoding y warnings[] para que los llamadores puedan verificar qué se ejecutó.

Modelo de Errores

Fallos de validación de entrada:

Error JSON-RPC -32602 (invalid params)

Fallos de herramientas:

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

Códigos de error comunes de herramientas:

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

Variables de Entorno

Variable	Predeterminado	Efecto
`MCP_BEAM_STRICT_PATH_POLICY`	`false`	Habilita la aplicación estricta de la lista de permitidos de rutas de archivos/subtítulos.
`MCP_BEAM_ALLOWED_PATH_PREFIXES`	vacío	Prefijos absolutos separados por comas permitidos en modo estricto.
`MCP_BEAM_ALLOW_LOOPBACK_URLS`	`false`	Permite hosts de URL `localhost`/loopback cuando `true`.
`MCP_BEAM_ALLOW_WILDCARD_BIND`	`false`	Permite direcciones de enlace comodín cuando `true`.
`MCP_BEAM_LOG_LEVEL`	`info`	Nivel de registro del servidor: `debug`, `info`, `warn`, `error`.
`MCP_BEAM_HANDLE_SIGINT`	`false`	Maneja `SIGINT` internamente cuando `true`; por defecto, los hosts MCP controlan el manejo de interrupciones.

Seguridad

Controles de seguridad:

Las rutas de archivos locales deben ser absolutas.
El modo de ruta estricto aplica prefijos de lista de permitidos y rechaza escapes de ruta.
Solo se aceptan URLs http y https.
Los hosts loopback (localhost, 127.0.0.0/8, ::1) están bloqueados por defecto.
Las direcciones de enlace comodín (0.0.0.0, ::) están bloqueadas por defecto.
Las rutas de medios temporales usan tokens aleatorios e imposibles de adivinar.
La propiedad de la sesión es local al proceso y en memoria.

Línea base de producción recomendada:

Mantén MCP_BEAM_ALLOW_LOOPBACK_URLS=false a menos que se necesite explícitamente para pruebas solo locales.
Mantén MCP_BEAM_ALLOW_WILDCARD_BIND=false.
Habilita MCP_BEAM_STRICT_PATH_POLICY=true con MCP_BEAM_ALLOWED_PATH_PREFIXES explícito.
Ejecuta mcp-beam bajo una cuenta de sistema operativo con privilegios mínimos. Threat boundaries:
La entrada del cliente MCP no es confiable y se valida estrictamente.
Los hosts de URL de origen son límites de confianza externos.
Los listeners de medios son visibles en la LAN y deben ejecutarse solo en redes confiables.
Los endpoints de control de dispositivos (Chromecast/DLNA) dependen de la integridad de la LAN.

Arquitectura

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 ejecución:

Binario único sin interfaz gráfica.
MCP solo sobre stdin/stdout.
El administrador de sesiones en proceso es la fuente de verdad.
Una sesión activa por dispositivo de destino.

Flujo principal:

list_local_hardware: descubrir, normalizar, IDs estables, filtro de alcanzabilidad opcional.
beam_media: validar fuente, resolver destino, elegir protocolo, decidir transcodificación, iniciar reproducción, persistir sesión.
get_beaming_status: consultar sesiones activas por session_id o target_device.
play_beaming / pause_beaming: reanudar o pausar sesiones activas por session_id o target_device.
seek_beaming: buscar en sesiones activas por session_id o target_device.
stop_beaming: resolver sesión/dispositivo, detener reproducción del protocolo, liberar recursos de ejecución.

Valores predeterminados del ciclo de vida de la sesión:

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

Fuentes de estado:

Chromecast mediante sondeo de estado (GetStatus)
Monitoreo híbrido DLNA (callbacks + sondeo de respaldo)

Solución de problemas

Diagnóstico rápido:

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

Registros detallados:

MCP_BEAM_LOG_LEVEL=debug mcp-beam

Problemas comunes:

FFMPEG_NOT_FOUND: instale ffmpeg/ffprobe, luego verifique PATH.
DEVICE_NOT_FOUND: ejecute list_local_hardware y reutilice el id devuelto.
DEVICE_UNREACHABLE: verifique que el destino esté encendido y sea alcanzable.
UNSUPPORTED_URL_PATTERN: la fuente debe ser enrutable http/https; solo para pruebas de bucle local, establezca MCP_BEAM_ALLOW_LOOPBACK_URLS=true.
UNSUPPORTED_SOURCE_FOR_PROTOCOL: destino Chromecast para .m3u8.
PROTOCOL_ERROR con política de enlace: use una dirección de enlace LAN concreta; establezca MCP_BEAM_ALLOW_WILDCARD_BIND=true solo en entornos controlados.
invalid params: elimine campos desconocidos y haga coincidir nombres/tipos de argumentos exactos.

Problemas de descubrimiento:

Si no se devuelven dispositivos, aumente timeout_ms.
Establezca include_unreachable=true para depuración.
Verifique el acceso de descubrimiento de red/firewall.

Problemas de inicio:

Verifique la ruta del comando y los permisos del ejecutable.
En Windows, use la ruta completa a mcp-beam.exe.
En los registros de depuración, verifique mcp_server_start, mcp_read_wait, mcp_message_received.

Desarrollo

Comandos comunes:

make test
make lint
make release
make clean

mcp-beam

Documentación

mcp-beam

Demo

Características destacadas

Tabla de Contenidos

Inicio Rápido

1) Agrega mcp-beam a la configuración de tu host MCP

2) Verifica el binario del servidor/la conexión del módulo

3) Ejecuta el flujo de herramientas

Instalación

Módulo publicado (recomendado)

Copia local

Binario descargado

Dependencias de Ejecución

Instalación de Go

Linux

macOS

Windows

Verificar Instalación

Referencia de Herramientas

list_local_hardware

beam_media

get_beaming_status

play_beaming

pause_beaming

stop_beaming

seek_beaming

Comportamiento de Transcodificación

Modelo de Errores

Variables de Entorno

Seguridad

Arquitectura

Solución de problemas

Desarrollo

1) Agrega `mcp-beam` a la configuración de tu host MCP

`list_local_hardware`

`beam_media`

`get_beaming_status`

`play_beaming`

`pause_beaming`

`stop_beaming`

`seek_beaming`