OBS MCP

OBS MCP는 MCP 클라이언트에 OBS Studio의 최신 상태를 검사할 수 있는 인터페이스를 제공합니다. 씬, 소스, 오디오, 전환, 필터, 녹화, 스트리밍, 캔버스 및 나머지 OBS WebSocket v5 요청 표면에 대한 155개의 도구를 노출합니다.

이 서버는 MCP 2026-07-28을 기준으로 빌드되었으며, 레거시 2025 시대 클라이언트도 계속 수용합니다. OBS가 닫혀 있어도 MCP 디스커버리는 계속 사용할 수 있으며, 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

포함 범위

• 현재 OBS Studio 소스 트리에 고정된 OBS WebSocket 프로토콜 개정판의 147개 요청 유형 전체

• 모든 도구에 대한 명시적 읽기 전용, 파괴적, 멱등적, 오픈 월드 주석

• 연결된 OBS 인스턴스가 광고하는 요청에 대한 런타임 기능 검사

• obs-describe-request를 통한 프로토콜 검사

• 번들된 OBS 프로토콜의 요청으로 제한되고 클라이언트 승인을 위해 파괴적 으로 표시된 일반 obs-call-request 탈출구

• 도구 인벤토리가 비공개 SDK 내부가 아닌 MCP를 통해 생성된 재현 가능한 .mcpb 빌드

명시적 도구가 일반적인 인터페이스로 남습니다. 일반 요청 도구는 새로 추가된 OBS 작업이 더 편리한 래퍼를 받기 전에 사용될 수 있도록 존재합니다.

요구 사항

• Node.js 20.19 이상

• WebSocket 서버가 활성화된 OBS Studio 28 이상

• MCP 2026-07-28 또는 호환되는 레거시 프로토콜을 지원하는 MCP 클라이언트

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 호환 데스크톱 클라이언트에서 해당 파일을 여세요. 패키지는 OBS WebSocket URL과 비밀번호를 요청합니다.

구성

서버는 비밀번호를 절대 출력하지 않습니다. 연결 및 프로토콜 진단은 stderr에 기록되므로 stdout은 MCP 메시지 전용으로 유지됩니다.

도구 표면

155개 도구는 더 작은 의견 기반 워크플로가 아닌 OBS 프로토콜을 중심으로 구성됩니다:

• 서버 상태, 버전 정보, 통계, 핫키 및 스튜디오 모드

• 씬, 그룹, 소스, 필터 및 씬 항목

• 입력 설정, 오디오 트랙, 볼륨, 음소거 상태, 미디어 컨트롤 및 디인터레이싱

• 녹화, 스트리밍, 리플레이 버퍼, 가상 카메라 및 출력 설정

• 전환, 전환 재정의, 전환 커서 및 T-Bar

• 캔버스, 스크린샷, 프로필, 씬 컬렉션 및 영구 데이터

• 프로토콜 설명 및 보호된 일반 요청 폴백

도구 디스커버리는 OBS 연결 없이도 작동합니다. OBS가 필요한 호출은 WebSocket 연결이 준비될 때까지 MCP 오류를 반환합니다.

적합한 용도

OBS MCP는 이미 명확한 결과가 있는 운영 작업에 잘 맞습니다: 씬 컬렉션 검사, 소스 생성 또는 배치, 오디오 상태 변경, 씬 전환, 스크린샷 촬영, 출력 상태 확인 또는 반복 가능한 녹화 설정 수행.

시각적 또는 편집적 판단을 대체하지는 않습니다. 프레이밍, 색상, 전환 타이밍, 오디오 밸런스 및 라이브 전환 결정은 여전히 결과를 보고 듣는 사람이 필요합니다.

안전 및 승인

모든 도구는 네 가지 MCP 동작 힌트를 모두 게시합니다. 읽기 전용 검사는 상태 변경과 분리되며, 더 광범위한 결과를 초래하는 작업은 적절하게 파괴적 또는 오픈 월드로 표시됩니다.

다음 도구에 대한 승인에 특히 주의하세요:

• 스트리밍, 녹화, 가상 카메라, 리플레이 버퍼 또는 다른 출력을 시작하거나 중지하는 도구

• 프로필 또는 씬 컬렉션을 전환하는 도구

• 핫키를 트리거하거나 OBS UI 요소와 상호 작용하는 도구

• 공급업체 요청을 호출하는 도구

• 파일을 저장하거나 일반 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로 빌드되며 TypeScript 컴파일러 API를 가져오지 않습니다. 향후 생성기, 린터 또는 빌드 도구가 프로그래밍 방식 컴파일러 액세스를 필요로 하는 경우, 애플리케이션 컴파일러가 TypeScript 7에 유지되는 동안 해당 도구를 TypeScript 6에 유지하세요. TypeScript 7.0은 프로그래밍 방식 API를 제공하지 않습니다. Microsoft는 TypeScript 7.0 릴리스 노트에서 TypeScript 6 호환성 패키지의 병행 사용을 문서화합니다.

프로토콜 기준

이 개정판은 다음 정확한 소스를 기준으로 검사되었습니다:

• MCP 사양: cbd57657

• MCP TypeScript 서버 및 클라이언트 SDK: 2.0.0

• OBS Studio: 0043697f

• OBS WebSocket: 1ef34bf4, 해당 OBS Studio 체크아웃에 고정된 개정판

생성된 프로토콜 파일은 docs/ 아래에 있습니다. 테스트는 도구 모듈에서 사용하는 모든 요청을 번들된 프로토콜과 비교하므로, 더 이상 사용되지 않는 요청 이름과 누락된 래퍼는 로컬에서 실패합니다.

프로젝트 역사

이 프로젝트는 Roy Shilkrot의 obs-mcp에서 시작되었으며, Zeke Sikelianos의 업스트림 작업을 포함합니다. 또한 Jag-k의 MCPB 패키징 및 registerTool 마이그레이션 작업을 보존합니다. 그들의 원래 커밋과 저작권은 Git 기록에 남아 있습니다.

라이선스

OBS MCP는 GPL-2.0-only로 라이선스가 부여됩니다. 게시된 npm 및 MCPB 패키지에는 해당 TypeScript 소스와 빌드 스크립트가 포함됩니다. LICENSE 및 NOTICE.md를 참조하세요.