OBS MCP

OBS MCP предоставляет MCP-клиентам актуальный и инспектируемый интерфейс к OBS Studio. Он предоставляет 155 инструментов для сцен, источников, аудио, переходов, фильтров, записи, стриминга, холстов и остальной поверхности запросов OBS WebSocket v5.

Сервер построен на основе MCP 2026-07-28 и по-прежнему принимает устаревших клиентов эпохи 2025 года. Обнаружение MCP остаётся доступным, когда OBS закрыт, а сервер переподключается в фоновом режиме, когда OBS возвращается.

Как это работает

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

OBS MCP работает как отдельный процесс Node.js. Он не модифицирует OBS и не требует плагина OBS; он использует встроенный в OBS Studio WebSocket-сервер. MCP обрабатывает обнаружение инструментов, схемы, результаты и подсказки одобрения. OBS WebSocket обрабатывает живое состояние приложения.

Related MCP server: obs-mcp-server

Что охватывается

• Все 147 типов запросов в протоколе OBS WebSocket, закреплённых текущим деревом исходников OBS Studio

• Явные аннотации только для чтения, деструктивные, идемпотентные и открытые для всех инструментов

• Проверка возможностей во время выполнения на основе запросов, рекламируемых подключённым экземпляром OBS

• Инспекция протокола через obs-describe-request

• Универсальный запасной вариант obs-call-request, ограниченный запросами из встроенного протокола OBS и помеченный как деструктивный для одобрения клиентом

• Воспроизводимая сборка .mcpb с инвентарём инструментов, генерируемым через MCP, а не через внутренние механизмы SDK

Явные инструменты остаются обычным интерфейсом. Универсальный инструмент запроса существует, чтобы недавно добавленная операция OBS могла быть использована до того, как получит более эргономичную обёртку.

Требования

• Node.js 20.19 или новее

• OBS Studio 28 или новее с включённым WebSocket-сервером

• MCP-клиент, поддерживающий MCP 2026-07-28 или совместимый устаревший протокол

OBS включает WebSocket v5. Включите его в Инструменты > Настройки WebSocket-сервера. Новые запросы OBS доступны только тогда, когда подключённая версия их рекламирует; неподдерживаемые вызовы возвращают описательную ошибку.

Установка из исходников

Этот независимый репозиторий пока не имеет собственного npm-релиза. Пока его нет, запускайте его из локальной копии:

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

Затем укажите вашему MCP-клиенту на собранную точку входа:

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

Если OBS использует нестандартный адрес, добавьте OBS_WEBSOCKET_URL в блок окружения.

Проверка подключения

Откройте OBS, запустите новую сессию агента и спросите:

Проверьте подключение к OBS. Сообщите версию OBS, текущую сцену, статус стрима и статус записи. Ничего не меняйте.

Клиент должен запрашивать только инструменты только для чтения и возвращать живые значения из OBS. Если обнаружение инструментов работает, но подсказка сообщает, что OBS отключён, оставьте MCP-сервер запущенным и запустите OBS; переподключение произойдёт в фоновом режиме.

Установка пакета MCPB

Соберите настольный пакет локально:

npm run pack

Команда пересобирает сервер, читает публичный список инструментов через MCP, устанавливает только производственные зависимости в изолированную промежуточную директорию, проверяет манифест и записывает:

dist/obs-studio.mcpb

Откройте этот файл в MCPB-совместимом настольном клиенте. Пакет запрашивает URL и пароль WebSocket OBS.

Конфигурация

Сервер никогда не выводит пароль. Диагностика подключения и протокола записывается в stderr, чтобы stdout оставался зарезервированным для сообщений MCP.

Поверхность инструментов

155 инструментов организованы вокруг протокола OBS, а не более узкого субъективного рабочего процесса:

• статус сервера, информация о версии, статистика, горячие клавиши и студийный режим

• сцены, группы, источники, фильтры и элементы сцен

• настройки входов, аудиодорожки, громкость, состояние беззвучия, управление медиа и деинтерлейсинг

• запись, стриминг, буфер повтора, виртуальная камера и настройки вывода

• переходы, переопределения переходов, курсор переходов и T-Bar

• холсты, скриншоты, профили, коллекции сцен и постоянные данные

• описание протокола и защищённый универсальный запасной вариант запроса

Обнаружение инструментов работает без подключения к OBS. Вызовы, требующие OBS, возвращают ошибку MCP, пока WebSocket-соединение не будет готово.

Где это применимо

OBS MCP хорошо подходит для операционной работы, у которой уже есть чёткий результат: проверка коллекции сцен, создание или упорядочивание источников, изменение состояния аудио, переключение сцен, создание скриншотов, проверка статуса вывода или выполнение повторяемой настройки записи.

Он не заменяет визуальное или редакторское суждение. Кадрирование, цвет, тайминг переходов, баланс аудио и решение выйти в эфир по-прежнему требуют человека, который смотрит и слушает результат.

Безопасность и одобрения

Каждый инструмент публикует все четыре подсказки поведения MCP. Инспекция только для чтения отделена от изменений состояния, а действия с более широкими последствиями помечены как деструктивные или открытые, где это уместно.

Обратите особое внимание на одобрения для инструментов, которые:

• запускают или останавливают стриминг, запись, виртуальную камеру, буфер повтора или другой вывод

• переключают профили или коллекции сцен

• запускают горячие клавиши или взаимодействуют с элементами интерфейса OBS

• вызывают запросы вендора

• сохраняют файлы или используют универсальный запасной вариант obs-call-request

obs-call-request принимает только типы запросов из встроенного протокола OBS, но его полезная нагрузка намеренно универсальна. Он всегда рекламируется как деструктивный и открытый, чтобы клиент не обрабатывал незнакомую операцию как безопасную.

Устранение неполадок

Инструменты появляются, но вызовы OBS не работают: убедитесь, что OBS открыт и его WebSocket-сервер включён. Процесс MCP остаётся доступным, пока он повторяет попытки подключения.

Сбой аутентификации: скопируйте пароль из Инструменты > Настройки WebSocket-сервера в OBS_WEBSOCKET_PASSWORD, затем перезапустите процесс MCP-сервера.

Агент не видит инструменты: перезапустите сессию агента или хост MCP, чтобы он создал новое stdio-соединение и перезагрузил список инструментов.

Запрос не поддерживается: подключённая сборка OBS не рекламировала этот WebSocket-запрос. Используйте операцию, поддерживаемую этой версией, или обновите OBS.

Процесс завершается или выдаёт ошибки протокола: проверьте stderr. stdout зарезервирован для трафика MCP и не должен перенаправляться в обычные журналы приложений.

Разработка

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

Запустите полный локальный набор проверок с помощью:

npm run check

Тесты покрывают рукопожатие OBS WebSocket и корреляцию запросов, параллельные попытки подключения, ограничение возможностей, точное соответствие запросов OBS, детерминированное обнаружение инструментов, аннотации и согласование как устаревшего, так и MCP 2026-07-28.

Политика TypeScript

Приложение собирается с TypeScript 7.0.2 и не импортирует API компилятора TypeScript. Если будущий генератор, линтер или инструмент сборки потребует программного доступа к компилятору, оставьте этот инструмент на TypeScript 6, пока компилятор приложения остаётся на TypeScript 7. TypeScript 7.0 не поставляет программный API; Microsoft документирует пакет совместимости TypeScript 6 для параллельного использования в примечаниях к выпуску TypeScript 7.0.

Базовые версии протокола

Эта ревизия была проверена по следующим точным источникам:

• Спецификация MCP: cbd57657

• TypeScript SDK MCP (сервер и клиент): 2.0.0

• OBS Studio: 0043697f

• OBS WebSocket: 1ef34bf4, ревизия, закреплённая этим checkout OBS Studio

Сгенерированные файлы протокола находятся в docs/. Тесты сравнивают каждый запрос, используемый модулями инструментов, с встроенным протоколом, поэтому устаревшие имена запросов и отсутствующие обёртки приводят к сбою локально.

История проекта

Этот проект начался с obs-mcp Роя Шилкрота, включая работу выше по течению от Зеки Сикелианоса. Он также сохраняет работу Jag-k по упаковке MCPB и миграции registerTool. Их оригинальные коммиты и авторство остаются в истории Git.

Лицензия

OBS MCP распространяется под лицензией GPL-2.0-only. Опубликованные пакеты npm и MCPB включают соответствующий исходный код TypeScript и скрипты сборки. См. LICENSE и NOTICE.md.