代理obs
模型上下文协议(MCP)服务器,使人工智能助手能够通过OBS WebSocket API控制OBS Studio。
概述
此MCP服务器为AI代理(如Claude)提供对OBS Studio的编程控制,通过自然语言交互实现自动场景切换、录制控制、流媒体管理等。
特性
- 81 MCP工具:全面控制OBS Studio在9个工具组中的操作
- 场景管理:列出、切换、创建和删除OBS场景
- 场景预设:保存和恢复源可见性配置
- 录音控制:开始、停止、暂停、恢复和监视录制
- 流媒体控制:启动、停止和监视流媒体
- 来源管理:列表和控制源可见性
- 音频控制:管理输入静音和音量级别
- 屏幕截图来源:具有定期图像捕获功能的AI视觉监控
- 代理场景设计:创建和操作源(文本、图像、颜色、浏览器、媒体)
- 帮助和发现:内置帮助工具,提供基于主题的指导
- 状态监控:查询OBS连接和运行状态
- 自动化规则:免提OBS控制的事件触发动作和预定任务
- 4 MCP资源:作为资源公开的场景、屏幕截图、屏幕截图URL和预设
- 14 MCP提示:用于常见任务和诊断的预构建工作流程
- MCP完工:提示参数和资源URI的自动补全
- 克劳德技能:用于高级AI编排的可共享技能包
- TUI仪表板:状态、配置和历史记录的终端界面(
--tui旗帜) - 网络仪表盘:基于浏览器的仪表板位于
http://localhost:8765/
先决条件
- 转到1.25.5+ - 下载
- OBS工作室28+ -包括内置的WebSocket服务器
- Git -用于版本控制
安装
选项1:使用Go安装(推荐)```bash
go install github.com/ironystock/agentic-obs@latest
这将安装 `agentic-obs` 二进制到你的 `$GOPATH/bin` 目录。
### 选项2:从源代码构建```bash
# Clone the repository
git clone https://github.com/ironystock/agentic-obs.git
cd agentic-obs
# Build with Make (recommended - includes version info)
make build
# Or build directly with Go
go build -o agentic-obs .
# Verify the build
./agentic-obs --version
有关跨平台构建、发布自动化和高级构建选项,请参阅 docs/BUILD.md.
配置OBS工作室
- 开放式OBS工作室
- 首选 工具→ WebSocket服务器设置
- 启用WebSocket服务器(默认端口:4455)
- 设置密码(可选但推荐)
- 注意您的连接详细信息
用法
运行服务器```bash
MCP server mode (default) - if installed via go install
agentic-obs
TUI dashboard mode - terminal interface for monitoring
agentic-obs --tui
agentic-obs -t
Or run directly from source
go run main.go
go run main.go --tui
Or use a built binary
./agentic-obs
### TUI仪表板
TUI仪表板提供了一个基于终端的界面,有四个视图:
- **状态**:OBS连接状态、服务器信息、统计信息
- **配置**:当前配置设置
- **历史**:可滚动的操作历史日志
- **文档**:带有终端渲染的嵌入式文档
导航方式 `1/2/3/4` 按键或Tab键,按 `q` 退出。
首次运行时,服务器将:
1. 自动检测OBS开启 `localhost:4455`
1. 如果自动检测失败,则提示连接详细信息
1. 将成功配置保存到SQLite
### 连接到MCP客户端
此服务器使用stdio传输。配置您的MCP客户端以执行 `agentic-obs` 命令。
Claude桌面配置示例(`claude_desktop_config.json`):```json
{
"mcpServers": {
"obs": {
"command": "agentic-obs"
}
}
}
注: 如果你是从源代码构建的,或者二进制文件不在你的PATH中,请使用完整路径:```json
{
"mcpServers": {
"obs": {
"command": "/full/path/to/agentic-obs"
}
}
}
## 可用的MCP工具
### 场景管理(4个工具)
|工具|说明|
|------|-------------|
| `list_scenes` |列出所有可用场景并标识当前场景|
| `set_current_scene` |切换到特定场景|
| `create_scene` |创建新场景|
| `remove_scene` |删除场景|
### 录音控制(5个工具)
|工具|说明|
|------|-------------|
| `start_recording` |开始录制|
| `stop_recording` |停止录制|
| `pause_recording` |暂停当前录制|
| `resume_recording` |恢复暂停的录制|
| `get_recording_status` |检查录制状态和详细信息|
### 流媒体控制(3个工具)
|工具|说明|
|------|-------------|
| `start_streaming` |开始流媒体播放|
| `stop_streaming` |停止流媒体播放|
| `get_streaming_status` |检查流媒体状态|
### 源代码管理(3个工具)
|工具|说明|
|------|-------------|
| `list_sources` |列出所有输入源|
| `toggle_source_visibility` |在场景中显示/隐藏源|
| `get_source_settings` |获取源配置|
### 音频控制(4个工具)
|工具|说明|
|------|-------------|
| `get_input_mute` |检查音频输入是否静音|
| `toggle_input_mute` |切换音频输入静音状态|
| `set_input_volume` |设置音频输入音量(dB或倍数)|
| `get_input_volume` |获取当前音量水平(dB和倍数)|
### 场景预设(6个工具)
|工具|说明|
|------|-------------|
| `save_scene_preset` |将当前场景源状态另存为命名预设|
| `list_scene_presets` |列出所有已保存的预设,可选择按场景过滤|
| `get_preset_details` |获取特定预设的详细信息|
| `apply_scene_preset` |应用已保存的预设以恢复源可见性|
| `rename_scene_preset` |重命名现有预设|
| `delete_scene_preset` |删除已保存的预设|
### 截图来源(4个工具)
|工具|说明|
|------|-------------|
| `create_screenshot_source` |为AI视觉监控创建定期截图捕获源|
| `remove_screenshot_source` |停止并删除屏幕截图捕获源|
| `list_screenshot_sources` |列出所有已配置的源及其状态和HTTP URL|
| `configure_screenshot_cadence` |更新截图源的捕获间隔|
### 状态和监控(1个工具)
|工具|说明|
|------|-------------|
| `get_obs_status` |获取OBS的整体状态和连接信息|
### 帮助和发现(1个工具)
|工具|说明|
|------|-------------|
| `help` |获取有关工具、资源、提示、工作流或故障排除的详细帮助|
### 场景设计(14个工具)
使AI能够以编程方式创建和操作OBS源。
#### 源代码创建
|工具|说明|
|------|-------------|
| `create_text_source` |使用可自定义的字体和颜色创建文本/标签源|
| `create_image_source` |从文件路径创建图像源|
| `create_color_source` |创建纯色源|
| `create_browser_source` |为web内容创建浏览器源|
| `create_media_source` |从文件创建媒体/视频源|
#### 布局控件
|工具|说明|
|------|-------------|
| `set_source_transform` |设置源的位置、比例和旋转|
| `get_source_transform` |获取当前变换属性|
| `set_source_crop` |为源设置裁剪值|
| `set_source_bounds` |为源设置边界类型和大小|
| `set_source_order` |设置z顺序索引(从前到后排序)|
#### 高级
|工具|说明|
|------|-------------|
| `set_source_locked` |锁定/解锁源以防止更改|
| `duplicate_source` |在场景内或跨场景复制源|
| `remove_source` |从场景中删除源|
| `list_input_kinds` |列出所有可用的输入源类型|
### 过滤器(7个工具)
|工具|说明|
|------|-------------|
| `list_source_filters` |列出应用于源的所有筛选器|
| `get_source_filter` |获取过滤器详细信息和设置|
| `create_source_filter` |为源添加新的过滤器(颜色校正、噪声抑制等)|
| `remove_source_filter` |从源中删除过滤器|
| `toggle_source_filter` |启用/禁用筛选器|
| `set_source_filter_settings` |修改过滤器配置|
| `list_filter_kinds` |列出所有可用的过滤器类型|
### 过渡(5个工具)
|工具|说明|
|------|-------------|
| `list_transitions` |列出所有可用转换和当前转换|
| `get_current_transition` |获取当前过渡详细信息|
| `set_current_transition` |更改活动过渡(剪切、淡入淡出、滑动等)|
| `set_transition_duration` |设置转换持续时间(毫秒)|
| `trigger_transition` |触发演播室模式转换(预览到节目)|
### 虚拟凸轮和回放缓冲区(6个工具)
|工具|说明|
|------|-------------|
| `get_virtual_cam_status` |检查虚拟摄像头输出是否处于活动状态|
| `toggle_virtual_cam` |打开/关闭虚拟相机|
| `get_replay_buffer_status` |检查重播缓冲区是否处于活动状态|
| `toggle_replay_buffer` |打开/关闭回放缓冲区|
| `save_replay_buffer` |将当前回放缓冲区保存到文件|
| `get_last_replay` |获取上次保存的回放的文件路径|
### 工作室模式和热键(6个工具)
|工具|说明|
|------|-------------|
| `get_studio_mode_enabled` |检查是否启用了演播室模式|
| `toggle_studio_mode` |启用或禁用工作室模式|
| `get_preview_scene` |获取当前预览场景(工作室模式)|
| `set_preview_scene` |设置预览场景(工作室模式)|
| `list_hotkeys` |列出所有可用的OBS热键|
| `trigger_hotkey_by_name` |按名称触发热键|
### 元工具(4个工具,始终启用)
|工具|说明|
|------|-------------|
| `help` |获取有关工具、资源、提示、工作流或故障排除的详细帮助|
| `get_tool_config` |查询当前工具组配置(启用/禁用状态)|
| `set_tool_config` |在运行时启用/禁用工具组(仅会话或持久)|
| `list_tool_groups` |列出所有工具组及其描述和状态|
**示例:禁用可视化工具以实现更轻松的设置**```json
{
"tool": "set_tool_config",
"arguments": {
"group": "Visual",
"enabled": false,
"persist": true
}
}
总计:9组81个工具 (核心、来源、音频、布局、视觉、设计、滤镜、过渡、自动化)+元(4个始终启用的工具)
MCP资源
服务器将OBS数据作为MCP资源公开,以实现高效访问和监控:
| 资源类型 | URI模式 | 内容类型 | 描述 |
|---|---|---|---|
| 场景 | obs://scene/{name} |
obs-scene (JSON) |
带源和设置的场景配置 |
| 屏幕截图 | obs://screenshot/{name} |
image/png 或 image/jpeg |
来自捕获源的二进制屏幕截图图像 |
| 屏幕截图URL | obs://screenshot-url/{name} |
text/plain |
用于访问屏幕截图图像的HTTP URL |
| 预设 | obs://preset/{name} |
obs-preset (JSON) |
具有源可见性的场景预设配置 |
用途:
resources/list-列出所有可用资源resources/read-获取详细的资源内容- 资源支持实时更新通知
- 补全:资源URI名称可自动完成
MCP提示
预构建的工作流程提示引导AI助手完成常见的OBS任务:
| 提示 | 论点 | 目的 |
|---|---|---|
stream-launch |
无 | 预流检查表和设置 |
stream-teardown |
none | 结束流清理工作流 |
audio-check |
无 | 音频验证和诊断 |
visual-check |
screenshot_source | 视觉布局分析 |
health-check |
无 | 全面的OBS诊断 |
problem-detection |
screenshot_source | 自动问题检测 |
preset-switcher |
preset_name(可选) | 场景预设管理 |
recording-workflow |
无 | 录制会话指南 |
scene-organizer |
无 | 场景组织和清理 |
quick-status |
无 | 简要状态摘要 |
scene-designer |
scene_name,action(可选) | 使用设计工具创建可视化布局 |
source-management |
scene_name | 管理源可见性和属性 |
visual-setup |
monitor_scene(可选) | 配置屏幕截图监控 |
automation-setup |
rule_type(可选)、trigger_event(可选) | 创建和管理自动化规则(FB-20) |
Prompts将多种工具组合成具有内置最佳实践的连贯工作流程。
补全:自动补全功能可用于提示参数(预设名称、屏幕截图来源、场景名称)。
发展
项目结构```
agentic-obs/
├── main.go # Entry point (MCP server or TUI)
├── config/ # Configuration management
├── internal/
│ ├── mcp/ # MCP server implementation (81 tools)
│ ├── obs/ # OBS WebSocket client
│ ├── storage/ # SQLite persistence
│ ├── http/ # HTTP server for screenshots and dashboard
│ ├── screenshot/ # Background capture manager
│ └── tui/ # Terminal UI dashboard
├── skills/ # Claude Skills packages
└── scripts/ # Development helpers
### 添加新工具
1. 在中定义工具架构 `internal/mcp/tools.go`
1. 实现处理程序功能
1. 服务器初始化中的注册工具
1. 在中添加OBS命令包装器 `internal/obs/commands.go` 如有需要
### 运行测试```bash
go test ./...
配置
配置存储在SQLite中(agentic-obs.db)包括:
- OBS-WebSocket连接详细信息(主机、端口、密码)
- 场景和源预设
- 用户偏好
故障排除
连接问题
问题:“无法连接到OBS”
解决方案:
- 确保OBS Studio正在运行
- 验证OBS中是否启用了WebSocket服务器(工具→ WebSocket服务器设置)
- 检查端口4455是否未被防火墙阻止
- 如果启用了身份验证,请确认密码匹配
权限问题
问题:数据库写入错误
解决方案:
- 确保目录可写
- 检查上的文件权限
agentic-obs.db
克劳德技能
这 skills/ 目录包含可共享的Claude Skills包,这些包教AI助手如何有效地编排代理obs工具:
| 技能 | 目的 |
|---|---|
streaming-assistant |
完整的流媒体工作流程(预流、直播、拆卸) |
scene-designer |
使用14个设计工具创建可视化布局 |
audio-engineer |
音频优化和故障排除 |
preset-manager |
预设生命周期和组织 |
技能使用渐进式披露进行代币高效指导。看 skills/README.md 用于安装。
未来的增强功能
- 自动化规则和宏
- 多实例OBS支持
- 实时事件通知
- 其他资源类型(过滤器、转换)
贡献
欢迎投稿!请打开问题或提交拉取请求。
许可证
[在此处添加您的许可证]
资源
- 模型上下文协议
- OBS WebSocket协议
- goobs图书馆
内置:
- 转到1.25.5
- MCP Go SDK v1.1.0
- goobs v1.5.6
- 冒泡/唇彩(TUI)
