OBS MCP

OBS MCP 为 MCP 客户端提供了对 OBS Studio 的实时、可检查接口。它公开了 155 个工具，涵盖场景、源、音频、转场、滤镜、录制、推流、画布以及 OBS WebSocket v5 请求面的其余部分。

该服务器针对 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-call-request 逃生舱口，仅限于捆绑的 OBS 协议中的请求，并标记为破坏性以供客户端审批

• 一个可重现的 .mcpb 构建，其工具清单通过 MCP 生成，而非私有 SDK 内部机制

显式工具仍然是正常接口。通用请求工具的存在是为了让新添加的 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 型推杆

• 画布、截图、配置文件、场景集合和持久数据

• 协议描述和受保护的通用请求回退

工具发现无需 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。如果将来的生成器、linter 或构建工具需要以编程方式访问编译器，请将该工具保留在 TypeScript 6 上，而应用程序编译器保留在 TypeScript 7 上。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。