OBS MCP

OBS MCP ofrece a los clientes MCP una interfaz actual e inspeccionable para OBS Studio. Expone 155 herramientas para escenas, fuentes, audio, transiciones, filtros, grabación, streaming, lienzos y el resto de la superficie de solicitudes de OBS WebSocket v5.

El servidor está construido sobre MCP 2026-07-28 y sigue aceptando clientes heredados de la era 2025. El descubrimiento de MCP sigue disponible cuando OBS está cerrado, y el servidor se reconecta en segundo plano cuando OBS vuelve.

Cómo funciona

MCP client  <-- stdio -->  OBS MCP  <-- WebSocket v5 -->  OBS Studio

OBS MCP se ejecuta como un proceso Node.js separado. No parchea OBS ni requiere un plugin de OBS; utiliza el servidor WebSocket integrado en OBS Studio. MCP gestiona el descubrimiento de herramientas, esquemas, resultados y avisos de aprobación. OBS WebSocket gestiona el estado de la aplicación en vivo.

Related MCP server: obs-mcp-server

Qué cubre

• Los 147 tipos de solicitud del protocolo OBS WebSocket fijados por el árbol de fuentes actual de OBS Studio

• Anotaciones explícitas de solo lectura, destructivas, idempotentes y de mundo abierto en cada herramienta

• Comprobaciones de capacidad en tiempo de ejecución contra las solicitudes anunciadas por la instancia de OBS conectada

• Inspección de protocolo a través de obs-describe-request

• Una vía de escape genérica obs-call-request, limitada a las solicitudes del protocolo OBS incluido y marcada como destructiva para la aprobación del cliente

• Una compilación reproducible .mcpb con su inventario de herramientas generado a través de MCP en lugar de los internals privados del SDK

Las herramientas explícitas siguen siendo la interfaz normal. La herramienta de solicitud genérica existe para que una operación de OBS recién añadida pueda usarse antes de que reciba un envoltorio más ergonómico.

Requisitos

• Node.js 20.19 o superior

• OBS Studio 28 o superior con el servidor WebSocket habilitado

• Un cliente MCP que soporte MCP 2026-07-28 o el protocolo heredado compatible

OBS incluye WebSocket v5. Actívalo en Herramientas > Configuración del servidor WebSocket. Las solicitudes más recientes de OBS solo están disponibles cuando la versión conectada las anuncia; las llamadas no compatibles devuelven un error descriptivo.

Instalar desde el código fuente

Este repositorio independiente aún no tiene su propio lanzamiento npm. Hasta entonces, ejecútalo desde una copia local:

git clone https://github.com/Tom-R-Main/OBS-MCP.git
cd OBS-MCP
npm ci
npm run check

Luego apunta tu cliente MCP al punto de entrada compilado:

{
  "mcpServers": {
    "obs": {
      "command": "node",
      "args": ["/absolute/path/to/OBS-MCP/build/index.js"],
      "env": {
        "OBS_WEBSOCKET_PASSWORD": "<password-from-obs>"
      }
    }
  }
}

Si OBS usa una dirección no predeterminada, añade OBS_WEBSOCKET_URL al bloque de entorno.

Verificar la conexión

Abre OBS, inicia una nueva sesión de agente y pregunta:

Comprueba la conexión de OBS. Informa de la versión de OBS, la escena actual, el estado de streaming y el estado de grabación. No cambies nada.

El cliente debería solicitar solo herramientas de solo lectura y devolver valores en vivo de OBS. Si el descubrimiento de herramientas funciona pero el prompt informa de que OBS está desconectado, deja el servidor MCP en ejecución y abre OBS; la reconexión se realiza en segundo plano.

Instalar el paquete MCPB

Compila el paquete de escritorio localmente:

npm run pack

El comando reconstruye el servidor, lee la lista de herramientas públicas a través de MCP, instala las dependencias de solo producción en un directorio de ensayo aislado, valida el manifiesto y escribe:

dist/obs-studio.mcpb

Abre ese archivo en un cliente de escritorio compatible con MCPB. El paquete solicita la URL y la contraseña de WebSocket de OBS.

Configuración

El servidor nunca imprime la contraseña. Los diagnósticos de conexión y protocolo se escriben en stderr para que stdout permanezca reservado para los mensajes de MCP.

Superficie de herramientas

Las 155 herramientas se organizan en torno al protocolo de OBS en lugar de un flujo de trabajo más concreto y subjetivo:

• estado del servidor, información de versión, estadísticas, atajos de teclado y modo estudio

• escenas, grupos, fuentes, filtros y elementos de escena

• configuración de entrada, pistas de audio, volumen, estado de silencio, controles multimedia y desentrelazado

• grabación, streaming, búfer de reproducción, cámara virtual y configuración de salida

• transiciones, anulaciones de transición, el cursor de transición y la barra T

• lienzos, capturas de pantalla, perfiles, colecciones de escenas y datos persistentes

• descripción del protocolo y la alternativa de solicitud genérica protegida

El descubrimiento de herramientas funciona sin conexión a OBS. Las llamadas que necesitan OBS devuelven un error de MCP hasta que la conexión WebSocket esté lista.

Dónde encaja

OBS MCP es adecuado para trabajos operativos que ya tienen un resultado claro: inspeccionar una colección de escenas, crear u organizar fuentes, cambiar el estado de audio, cambiar de escena, tomar capturas de pantalla, comprobar el estado de salida o llevar a cabo una configuración de grabación repetible.

No reemplaza el criterio visual o editorial. El encuadre, el color, el ritmo de las transiciones, el equilibrio de audio y la decisión de emitir en directo siguen necesitando a una persona que vea y escuche el resultado.

Seguridad y aprobaciones

Cada herramienta publica las cuatro pistas de comportamiento de MCP. La inspección de solo lectura se separa de los cambios de estado, y las acciones con consecuencias más amplias se marcan como destructivas o de mundo abierto según corresponda.

Presta especial atención a las aprobaciones de herramientas que:

• inician o detienen streaming, grabación, cámara virtual, búfer de reproducción u otra salida

• cambian de perfil o colección de escenas

• activan atajos de teclado o interactúan con elementos de la interfaz de OBS

• invocan solicitudes de proveedor

• guardan archivos o usan la alternativa genérica obs-call-request

obs-call-request solo acepta tipos de solicitud del protocolo OBS incluido, pero su carga útil es intencionadamente genérica. Siempre se anuncia como destructiva y de mundo abierto para que un cliente no trate silenciosamente una operación desconocida como segura.

Solución de problemas

Las herramientas aparecen, pero las llamadas a OBS fallan: asegúrate de que OBS esté abierto y su servidor WebSocket esté habilitado. El proceso MCP permanece disponible mientras reintenta la conexión.

La autenticación falla: copia la contraseña de Herramientas > Configuración del servidor WebSocket en OBS_WEBSOCKET_PASSWORD y reinicia el proceso del servidor MCP.

El agente no puede ver las herramientas: reinicia la sesión del agente o el host de MCP para que cree una nueva conexión stdio y recargue la lista de herramientas.

Una solicitud no es compatible: la compilación de OBS conectada no anunció esa solicitud de WebSocket. Usa una operación compatible con esa versión o actualiza OBS.

El proceso sale o emite errores de protocolo: inspecciona stderr. stdout está reservado para el tráfico de MCP y no debe redirigirse a los registros de aplicación normales.

Desarrollo

npm ci
npm run build
npm test
npm run validate:manifest

Ejecuta la comprobación local completa con:

npm run check

Las pruebas cubren el apretón de manos y la correlación de solicitudes de OBS WebSocket, los intentos de conexión concurrentes, la limitación de capacidades, la paridad exacta de solicitudes de OBS, el descubrimiento determinista de herramientas, las anotaciones y la negociación tanto heredada como MCP 2026-07-28.

Política de TypeScript

La aplicación se compila con TypeScript 7.0.2 y no importa la API del compilador de TypeScript. Si un generador, linter o herramienta de compilación futura necesita acceso programático al compilador, mantén esa herramienta en TypeScript 6 mientras el compilador de la aplicación permanezca en TypeScript 7. TypeScript 7.0 no incluye una API programática; Microsoft documenta el paquete de compatibilidad TypeScript 6 en paralelo en las notas de la versión de TypeScript 7.0.

Líneas base del protocolo

Esta revisión se comprobó contra estas fuentes exactas:

• Especificación MCP: cbd57657

• SDK de servidor y cliente TypeScript de MCP: 2.0.0

• OBS Studio: 0043697f

• OBS WebSocket: 1ef34bf4, la revisión fijada por esa copia de OBS Studio

Los archivos de protocolo generados se encuentran en docs/. Las pruebas comparan cada solicitud utilizada por los módulos de herramientas con el protocolo incluido, por lo que los nombres de solicitud obsoletos y los envoltorios faltantes fallan localmente.

Historia del proyecto

Este proyecto comenzó con el obs-mcp de Roy Shilkrot, incluido el trabajo ascendente de Zeke Sikelianos. También conserva el empaquetado MCPB y el trabajo de migración de registerTool de Jag-k. Sus confirmaciones originales y autoría permanecen en el historial de Git.

Licencia

OBS MCP está licenciado bajo GPL-2.0-only. Los paquetes publicados en npm y MCPB incluyen el código fuente de TypeScript correspondiente y los scripts de compilación. Consulta LICENSE y NOTICE.md.