OBS Studio MCP服务器

OBS Studio MCP Server

A .NET 10 MCP (Model Context Protocol) server for controlling OBS Studio. Use it standalone with any MCP client or via the included VS Code extension.

⚠️ This project is in active development. APIs and features may change.

Platform: Windows only (OBS WebSocket limitation)

Runtime and MCP Compatibility

• Uses .NET 10 with the stable MCP C# SDK 2.2.0 and OBS WebSocket library 5.7.0.
• Supports the current MCP revision (2026-07-28) and earlier clients using the initialization handshake.
• Preserves all seven tool names and audio-muted-by-default recording behavior.
• Failed tool calls include the existing error message and set the MCP isError flag.
• Recording format settings use the current OBS setting (RecFormat2) with compatibility for older OBS versions.
• The VS Code extension acquires .NET 10 automatically and uses that runtime to start the bundled server.

Features

Control OBS Studio through AI assistants (GitHub Copilot, Claude, etc.):

• Recording: Start, stop, pause, resume, configure format/quality (audio muted by default)
• Streaming: Start, stop, monitor status
• Scenes: List and switch scenes
• Sources: Add window captures, manage visibility
• Audio: Mute/unmute inputs, control volume (desktop audio, mic)
• Window Capture: Programmatically select windows to record
• Media: Screenshots

Installation

VS Code / VS Code Insiders (Recommended)

Install directly from the VS Code Marketplace:

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "OBS Studio MCP Server"
4. Click Install

Or run: code --install-extension sbroenne.obs-mcp

Other MCP Clients (Claude Desktop, Cursor, Windsurf, etc.)

Download from GitHub Releases:

Extract and add to your MCP client config. For VS Code, use the following mcp.json format:

{
  "servers": {
    "obs": {
      "command": "dotnet",
      "args": ["C:/Tools/obs-mcp-server/Sbroenne.ObsMcp.McpServer.dll"],
      "env": {
        "OBS_HOST": "${input:obs_host}",
        "OBS_PORT": "${input:obs_port}",
        "OBS_PASSWORD": "${input:obs_password}"
      }
    }
  },
  "inputs": [
    {
      "id": "obs_host",
      "type": "promptString",
      "description": "OBS WebSocket host",
      "default": "localhost"
    },
    {
      "id": "obs_port",
      "type": "promptString",
      "description": "OBS WebSocket port",
      "default": "4455"
    },
    {
      "id": "obs_password",
      "type": "promptString",
      "description": "OBS WebSocket password",
      "password": true
    }
  ]
}

Config file locations:

Claude Desktop, Cursor, and Windsurf use mcpServers rather than VS Code's servers and inputs format. For example:

{
  "mcpServers": {
    "obs": {
      "command": "dotnet",
      "args": ["C:\\Tools\\obs-mcp-server\\Sbroenne.ObsMcp.McpServer.dll"],
      "env": {
        "OBS_HOST": "localhost",
        "OBS_PORT": "4455",
        "OBS_PASSWORD": "your-obs-websocket-password"
      }
    }
  }
}

Keep configurations containing passwords private and out of source control.

Prerequisites

1. OBS Studio - Download from obsproject.com
2. OBS WebSocket - Built into OBS Studio 28.0+

Enable OBS WebSocket

1. Open OBS Studio
2. Go to Tools → WebSocket Server Settings
3. Enable WebSocket server
4. Note the port (default: 4455) and password
5. Click Apply

Available Tools

Note: Recording starts with audio muted by default. Use muteAudio=false to include audio.

Quick Start: Record a Window

Important: Without a capture source, recordings will be BLACK!

1. Connect: obs_connection(action: Connect)
2. Add source: obs_source(action: AddWindowCapture, sourceName: "My Capture")
3. List windows: obs_source(action: ListWindows, sourceName: "My Capture")
4. Select window: obs_source(action: SetWindowCapture, sourceName: "My Capture", windowValue: "...")
5. Record: obs_recording(action: Start) or obs_recording(action: Start, path: "C:/Videos")

Or just ask your AI assistant: "Record VS Code in OBS"

Development

Build & Test

Use the .NET 10 SDK. global.json accepts stable .NET 10 SDK updates without switching to a newer major version.

# Build
dotnet build

# Run unit tests (no OBS required)
dotnet test --filter "Category!=Integration"

# Run integration tests (requires OBS with .env configured)
dotnet test --filter "Category=Integration"

# Compile and test the VS Code wrapper
npm ci --prefix vscode-extension
npm test --prefix vscode-extension

The tests that do not require OBS cover tool schemas, failures, prompts, resources, and actual server processes with current and earlier MCP clients. The OBS integration tests require a running OBS instance and fail if it is unavailable.

Pull requests run the server build, tests, standalone publish, and VS Code packaging on Windows. Dependabot checks NuGet, npm, and GitHub Actions updates weekly.

Project Structure

mcp-server-obs/
├── src/ObsMcp.McpServer/       # .NET 10 MCP Server
│   └── Tools/                  # 7 resource-based tools
├── tests/                      # Unit & integration tests
├── vscode-extension/           # VS Code extension wrapper
└── .github/workflows/          # Release automation

Release

• MCP Server: Push tag mcp-v1.0.0 → Builds standalone zips
• VS Code Extension: Push tag vscode-v1.0.0 → Builds .vsix + publishes to Marketplace

License

MIT