代理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安装（推荐）

go install github.com/ironystock/agentic-obs@latest

这将安装 agentic-obs 二进制到你的 $GOPATH/bin 目录。

选项2：从源代码构建

# 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）
设置密码（可选但推荐）
注意您的连接详细信息

用法

运行服务器

# 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 退出。

首次运行时，服务器将：

自动检测OBS开启 localhost:4455
如果自动检测失败，则提示连接详细信息
将成功配置保存到SQLite

连接到MCP客户端

此服务器使用stdio传输。配置您的MCP客户端以执行 agentic-obs 命令。

Claude桌面配置示例(claude_desktop_config.json):

{
  "mcpServers": {
    "obs": {
      "command": "agentic-obs"
    }
  }
}

注：如果你是从源代码构建的，或者二进制文件不在你的PATH中，请使用完整路径：

{
  "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`	列出所有工具组及其描述和状态

示例：禁用可视化工具以实现更轻松的设置

{
  "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

添加新工具

在中定义工具架构 internal/mcp/tools.go
实现处理程序功能
服务器初始化中的注册工具
在中添加OBS命令包装器 internal/obs/commands.go 如有需要

运行测试

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支持
实时事件通知
其他资源类型（过滤器、转换）

贡献

欢迎投稿！请打开问题或提交拉取请求。

许可证

\[在此处添加您的许可证\]

资源

______________________________________________________________________

内置：

转到1.25.5
MCP Go SDK v1.1.0
goobs v1.5.6
冒泡/唇彩（TUI）

Agentic Obs

快速接入

详细介绍