内容
<h1 align="center">OBS-MCP</h1>
<p align="center">
<strong>通过模型上下文协议为OBS Studio提供AI驱动的流媒体和录制控制</strong>
</p>
<p align="center">
<a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green.svg" alt="License" /></a>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-purple.svg" alt="MCP Compatible" /></a>
<a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-0.1.0-orange.svg" alt="v0.1.0" /></a>
<a href="#development"><img src="https://img.shields.io/badge/tests-pytest-0A9EDC.svg" alt="pytest" /></a>
<a href="https://obsproject.com/"><img src="https://img.shields.io/badge/OBS%20Studio-28%2B-red.svg" alt="OBS Studio 28+" /></a>
</p>
<p align="center">
<a href="#quick-start">快速开始</a> •
<a href="#features">功能</a> •
<a href="docs/TOOLS.md">工具参考</a> •
<a href="docs/ARCHITECTURE.md">架构</a> •
<a href="#troubleshooting">故障排除</a>
</p>
---
OBS-MCP 将任何支持模型上下文协议（MCP）的AI助手连接到 [OBS Studio](https://obsproject.com/)，使其能够完全控制您的流媒体和录制过程，涵盖整个 [obs-websocket v5](https://github.com/obsproject/obs-websocket) 协议 — 场景、源、场景项目、输入和完整的音频混音器、过滤器、过渡效果、流媒体、录制、虚拟摄像头、重播缓冲区、媒体播放、演播室模式和目标输出统计数据。在原始控制之上，它提供了 **管道工具**，这些工具通过一次调用即可完成实际工作，而不是让AI手动组装过滤器链 — `clean_audio_input` 建立了一个经过验证的噪声门 → 噪声抑制 → 压缩器链，而不是猜测OBS内部的过滤器参数名称。
**OBS-MCP本身在您的机器上运行。** 它是一个本地WebSocket客户端，直接与OBS Studio内置的 `obs-websocket` 服务器通信 — 您的流媒体、录制和场景设置永远不会离开您的计算机。AI“大脑”可以在您已经运行它的任何地方：Claude Desktop / Claude Code / Cursor / 任何MCP客户端。您带来AI，OBS-MCP处理OBS。
### 兼容性
OBS-MCP与任何支持 [模型上下文协议](https://modelcontextprotocol.io)的AI客户端兼容：
- [Claude Desktop](https://claude.ai/download) — Anthropic的桌面应用程序
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — CLI代理
- [Cursor](https://www.cursor.com/) — 带有MCP支持的AI代码编辑器
- 任何其他 [MCP兼容客户端](https://modelcontextprotocol.io/clients)
---
## 快速开始
### 1. 获取OBS-MCP
**选项A：** 点击上面的绿色 **代码** 按钮 → **下载ZIP** → 解压到一个文件夹
**选项B：** 使用git克隆：
```bash
git clone https://github.com/xDarkzx/OBS_MCP.git
```
### 2. 安装
```bash
cd OBS_MCP
pip install -e .
```
这为您提供了 `obs-mcp` 命令。
### 3. 在OBS中启用WebSocket服务器
OBS Studio从v28开始内置 `obs-websocket` — 无需安装。
1. 打开OBS Studio。
2. **工具 → WebSocket服务器设置**。
3. 勾选 **启用WebSocket服务器**。
4. 记录 **服务器端口** （默认为 `4455`）。
**尚未设置密码？** 留空并跳到步骤4 — `OBS_PASSWORD` 留空。
**已经有密码** （来自Stream Deck集成、聊天机器人或早期设置）？不要从记忆中重新输入 — 点击 **显示连接信息** 在同一个设置窗口中，显示OBS存储的精确密码。从那里复制。
### 4. 将OBS-MCP添加到您的AI客户端
```json
{
"mcpServers": {
"obs": {
"command": "obs-mcp",
"env": {
"OBS_HOST": "localhost",
"OBS_PORT": "4455",
"OBS_PASSWORD": "your_password_here"
}
}
}
}
```
如果您在OBS中没有设置密码，请留空 `OBS_PASSWORD` （`""`）。如果您的密码包含 `"` 或 `\`，请为JSON转义（ `\"` / `\\`）— 其他内容可以按原样输入。请查看客户端的MCP文档以获取配置文件位置。详细步骤： [安装指南](docs/INSTALLATION.md)。
### 5. 与您的AI对话
OBS运行并启用WebSocket服务器后，请要求您的AI助手切换场景、开始流媒体、清理麦克风音频或检查丢帧统计 — 它现在有真正的工具来完成这些。
---
## 功能
| 类别 | 工具 | 功能 |
|----------|:-----:|---------------|
| **常规** | 9 | 版本/统计数据、热键、自定义事件、供应商请求、持久数据存储 |
| **配置** | 15 | 场景集合、配置文件、视频/画布设置、流媒体服务目标、录制目录 |
| **源** | 3 | 活动状态检查和截图 — 适用于输入和场景 |
| **场景** | 12 | 列出/创建/删除/重命名场景、程序/预览控制、每场景过渡覆盖、画布、组 |
| **输入和音频** | 28 | 创建/配置输入；完整混音器 — 静音、音量、平衡、同步偏移、监视类型、音频轨道路由、去隔行模式 |
| **过渡** | 9 | 列出/设置过渡、持续时间、设置、T-bar scrubbing、触发过渡（包括演播室模式） |
| **过滤器** | 10 | 源过滤器链上的完整CRUD — 音频和视频效果、任意顺序 |
| **场景项目** | 17 | 变换（位置/缩放/裁剪）、启用/锁定状态、z-order、混合模式 |
| **输出** | 17 | 虚拟摄像头、重播缓冲区和任何通用命名输出 |
| **流媒体和录制** | 14 | 开始/停止/切换、字幕、暂停/恢复、文件分割、章节标记 |
| **媒体** | 4 | 媒体源的播放控制 — 状态、查找、播放/暂停/停止/重启/下一个/上一个 |
| **UI** | 8 | 演播室模式、属性/过滤器/交互对话框、监视器列表、投影仪 |
| **管道** | 2 | `clean_audio_input` — 一键噪声门 → 抑制 → 压缩器链，带有验证的OBS过滤器参数。 `diagnose_av_health` — 一键帧丢失/拥塞/磁盘空间诊断，而不是原始统计数据 |
**148种工具** — 完整的obs-websocket v5协议覆盖（唯一的故意省略，`Sleep`，仅在请求批次内起作用，而此版本尚未实现）加上上述两个复合管道工具。
### `clean_audio_input` — 管道工具
这里的每个其他工具都是一个薄的、忠实的obs-websocket请求包装器。这个工具不是 — 它是一个真正的流媒体者想要的东西（“使我的麦克风声音清洁”）而不是机制（“使用正确的内部参数名称按正确顺序创建三个过滤器”）：
```
clean_audio_input(input_name="Mic/Aux")
```
在正确的信号顺序下，构建一个噪声门 → 噪声抑制（RNNoise） → 压缩器链，使用针对OBS Studio实际过滤器源（`plugins/obs-filters/*.c`）验证的参数键 — 而不是从UI猜测。
### `diagnose_av_health` — “为什么我的流媒体丢帧？”
```
diagnose_av_health()
```
拉取 `GetStats` + `GetStreamStatus` + `GetRecordStatus` 并在一个调用中解释它们，而不是提供原始数字：渲染线程跳过率指向GPU/场景瓶颈，输出线程跳过低网络拥塞指向编码器，高拥塞指向您的上传/比特率，低磁盘空间在它静默杀死录制之前被标记。要求您的AI“为什么我的帧正在掉落”或“我的流媒体健康吗”，它有真正的数字可以推理，而不是猜测。
---
## 要求
- **OBS Studio 28+** （obs-websocket v5从v28开始内置）
- **Python 3.10+**
- 支持MCP的AI客户端
---
## 故障排除
| 问题 | 修复 |
|---------|-----|
| “无法连接到OBS” | 确保OBS Studio正在运行，并且工具 → WebSocket服务器设置 → 启用WebSocket服务器已勾选。 |
| “身份验证失败” | 您的 `OBS_PASSWORD` 环境变量与OBS的WebSocket服务器设置中设置的密码不匹配 — 或者您在OBS中设置了密码，但环境变量留空。不要从记忆中重新输入密码：工具 → WebSocket服务器设置 → **显示连接信息** 显示OBS存储的确切值。 |
| 工具调用挂起 | 检查OBS本身是否显示阻塞对话框（例如“场景集合已更改”提示） — 一些请求阻塞直到用户关闭OBS侧的UI。 |
| 场景/输入“未找到”错误 | 名称区分大小写，必须与OBS中显示的完全匹配。先调用 `get_scene_list` / `get_input_list`。 |
---
## 开发
```bash
# 安装开发依赖
pip install -e ".[dev]"
# 运行测试
pytest tests/ -x -q
```
### 添加新工具
1. 在 `obs_mcp/tools/` 中创建一个模块（或添加到现有的模块）。
2. 导出一个 `register(mcp: FastMCP)` 函数。
3. 使用 `@mcp.tool()` 装饰器定义您的工具，调用 `client.execute("RequestType", **params)`。
4. 在 `tool_registry.py` 中添加模块名称到 `_EXPECTED_MODULES`。
5. 就是这样 — 工具注册表在启动时自动发现它。
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 获取完整指南。
---
## 支持
发现了错误或想要一个功能？ [打开一个问题](https://github.com/xDarkzx/OBS_MCP/issues)。
如果OBS-MCP帮助了您的流媒体，请考虑给我买一杯咖啡：
<p align="center">
<a href="https://buymeacoffee.com/xdarkzx">
<img src="https://img.shields.io/badge/Buy_Me_A_Coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black" alt="Buy Me A Coffee" />
</a>
</p>
您的支持有助于保持该项目为每个人维护和免费。
---
## 文档
- **[安装指南](docs/INSTALLATION.md)** — 适用于Windows、macOS、Linux和每个支持的MCP客户端的详细设置
- **[工具参考](docs/TOOLS.md)** — 每个工具按域分组，附带一句话描述和签名
- **[架构](docs/ARCHITECTURE.md)** — 连接层、工具注册表、管道工具、协议参考
- **[贡献](CONTRIBUTING.md)** — 如何添加工具和贡献
- **[更新日志](CHANGELOG.md)** — 版本历史和发布说明
## 许可证
Apache License 2.0 — 见 [LICENSE](LICENSE) 获取详细信息。
由 [Daniel Hodgetts](https://github.com/xDarkzx) • [𝕏 @daehonz1](https://x.com/daehonz1) 构建
