obs-action-history

一个能“听见”的 OBS Studio MCP 服务器。

这类服务器已经有好几个了。大多数都是一次一个调用地包装 obs-websocket 的请求接口，然后就此打住。构建这样的工具是合理的，它能得到一个可以熟练操作 OBS 的工具。但它也会得到一个在特定且重要的方面“失聪”的工具。

这个服务器订阅事件流，保留一份有界的历史记录，并回答关于这些事件的问题。

零依赖。仅使用 Node 内置模块。支持 Windows、macOS 和 Linux。

关键区别

一个请求只能回答一种问题：此刻什么是真的。你提问，OBS 回答，你决定。两次调用之间发生了什么，已经消失，你无法知道它曾经存在过。

这听起来像是一个架构上的脚注。其实不是。想想它让你付出了什么代价。

obs-websocket 协议中没有返回音频电平的请求。 GetInputVolume 给你推子位置。GetInputMute 给你一个布尔值。两者都无法说明声音是否真的从那个麦克风里出来。电平只存在于一个地方，即 InputVolumeMeters，它是一个事件。

所以“我的麦克风现在是否正常工作”这个问题，无法由一个纯粹基于请求构建的服务器来回答。不是回答得不好，不是回答得慢，而是根本无法回答。一个暴露了 148 个工具的服务器，与一个只暴露 12 个工具的服务器，有着完全相同的盲点，因为答案不在它们所依赖的表面上。

这个服务器持有那个事件流：

obs_who_is_talking  ->  Mic A    peak -36.9 dB   29 samples
                        Mic B    peak -37.8 dB   29 samples
                        Music    peak -54.2 dB   29 samples

InputVolumeMeters 每个源大约每秒到达五十次。没有人希望从工具调用中拿回三千个原始帧。人们真正的问题是谁的声音大，所以电平永远不会进入缓冲区。它们被缩减为每个源的峰值，并作为答案返回。

这具体能给你带来什么

一个配置正确但毫无输出的麦克风。 推子位于 unity，未静音，但选择了错误的设备，或者线缆悄悄断了。请求能触及的每个设置都报告完美健康。这不是假设；这正是这个服务器诞生之前，它所来自的设备需要一个单独的麦克风检查进程的原因。

一个跟随声音的摄像头。 你需要知道两个麦克风哪个更响，并且是持续地知道，而且你需要将它们相互比较，而不是与某个固定阈值比较，因为同一个房间里的两个麦克风有不同的增益，而且每个麦克风都能听到所有人。这里没有可轮询的东西。信息只会在发生时到达。

一个活着但卡住的东西，比死掉的东西更糟糕。 在开发过程中，这个服务器调查了五个媒体源，每一个都报告 PLAYING。其中一个的进度为零毫秒，而其他几个移动了大约 2,540。从状态上看，它们无法区分。只有经过的时间才能区分一个正常工作的源和一个死掉的源，而正是这种盲点，已经让十七个小时的无声音乐隐藏在一个显示绿色的仪表盘后面。

两分钟前发生了什么。 轮询器只能描述现在，其他什么都做不了。一旦事情过去，它就完全不可用了，你只能对你想解释的那个事件进行猜测。

描述是产品的一部分

工具描述不是用来复述参数列表的地方。模型已经能读取 schema。它是用来放置那些否则会以昂贵方式学到的东西的地方：

• OBS 音频同步偏移上限接近 960 毫秒。更大的值会静默地应用为无效，所以你以为你补偿了两秒的延迟，实际上你一点都没补偿。

• 场景项索引 0 是底部，一个全画布源放在背景之上会完全遮住它，而且不会在任何地方报错。

• 一个放在画布外的源仍然可见，并且仍然播放其音频。隐藏它反而会切断音频，这就是为什么一个纯音频的叠加层是停放在画布外而不是隐藏起来。

• RemoveInput 报告成功，但不会删除任何仍被引用的源。

• 除非先设置 boundsType，否则边界字段是无效的。

• TriggerHotkeyByName 接受一个裸名称，而 libobs.mute 在每个音频源上注册一次，在参考机器上注册了二十四次。因此，热键无法针对特定源，无论你可能合理地假设什么。

这些每一条都让某人付出了代价。它们被写下来，是因为一个不知道这些的模型会自信地行动并出错，这比犹豫不决但正确要糟糕得多。

让全新机器成为可能的工具

obs_input_property_items 枚举了源属性背后的真实选择：每个摄像头和每个音频设备，以及 OBS 实际期望的标识符。

Microphone (Some USB Mic)
  -> {0.0.1.00000000}.{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}

其中没有任何人类可读的东西可以猜测。没有这个调用，助手只能调整人们已经手动创建的源。有了它，它就能从零开始构建它们。

覆盖范围

跨十一个模块共 67 个工具。

安装

你需要 Node 22 或更新版本，用于全局 WebSocket，以及 OBS 31+，并勾选 工具 → WebSocket 服务器设置 → 启用 WebSocket 服务器。

将 .mcp.example.json 复制到你的 MCP 客户端配置中，并将 args 指向 server.js。当设置了 OBS_WEBSOCKET_PASSWORD 时，密码从该环境变量读取，否则从服务器旁边的 secrets.json 读取：

{ "obsPassword": "the value from OBS > Tools > WebSocket Server Settings" }

请注意，错误的密码不会表现为错误的密码。OBS 接受套接字，然后用代码 4009 关闭它，大多数客户端会将其报告为超时，你会花一下午调查你的网络。这个服务器会正确地指出这一点。

参考机器

全文引用的数字，例如 43 种滤镜类型、411 个热键（其中只有 88 个是不同的）、960 毫秒的上限、五个输出和两个回放缓冲区，都是在 Windows 上的 OBS 32.2.1 和 obs-websocket 5.7.4 上测量的，当时那台机器正在向三个平台进行直播。这就是参考机器在文中出现时所指的内容。你的安装会在某些地方有所不同，而且这些数字中的每一个都可以用这里的工具检查，这正是陈述它们而不是把它们四舍五入成模糊概念的意义所在。

已发布的 obs-websocket 文档中有两个错误就是这样发现的，并且已经绕过了。GetSourceFilterKindList 返回 sourceFilterKinds，而文档说的是 filterKinds。还有 SetSourceFilterSettings.overlay 默认值为 true，而摘要声称是 false；传递 false 会调用 obs_source_reset_settings，并销毁该滤镜上所有其他已调优的值，这种错误你只会犯一次。

贡献

mcp/tools/index.js 持有契约。一个模块导出 (obs) => [ { name, description, inputSchema, handler } ]，并且只能使用 obs.request(type, data)，没有其他。

加载是故意故障安全的。一个缺失、在构建时抛出异常、返回格式错误的工具或重复名称的模块会被记录并跳过，服务器仍然会以其他所有内容完好地启动。你损坏的模块是你自己的问题，不应该成为别人的直播中断。

在提交拉取请求之前：

npm run preflight

它拒绝树中任何位置的凭据、绝对路径、机器特定地址和设备标识符，并验证每个模块仍然能加载。

状态

0.1.0。工具名称在 1.0 之前可能还会变动。如果你要针对它们编写脚本，请固定一个精确版本。

许可证

MIT。参见 LICENSE。