OBS_MCP

AI-powered stream and recording control for OBS Studio via MCP — 148 tools for scenes, audio mixer, filters, streaming, recording, and stream health diagnostics.

Generate Convert Improve

Install / Use

claude mcp add xDarkzx -- npx -y github:xDarkzx/OBS_MCP

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill

🔌

MCP Server

Model Context Protocol server

Quality Score

83/100

Skill content

View source on GitHub

<h1 align="center">OBS-MCP</h1> <p align="center"> <strong>AI-powered stream and recording control for OBS Studio through the Model Context Protocol</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.2.0-orange.svg" alt="v0.2.0" /></a> <a href="https://pypi.org/project/obs-mcp/"><img src="https://img.shields.io/pypi/v/obs-mcp.svg?color=blue" alt="PyPI" /></a> <a href="https://github.com/xDarkzx/OBS_MCP/actions/workflows/ci.yml"><img src="https://github.com/xDarkzx/OBS_MCP/actions/workflows/ci.yml/badge.svg" alt="CI" /></a> <a href="https://obsproject.com/"><img src="https://img.shields.io/badge/OBS%20Studio-28%2B-red.svg" alt="OBS Studio 28+" /></a> <a href="https://github.com/sponsors/xDarkzx"><img src="https://img.shields.io/badge/Sponsor-30363D?logo=githubsponsors&logoColor=EA4AAA" alt="Sponsor" /></a> </p> <p align="center"> <a href="#quick-start">Quick Start</a> • <a href="#new-here-what-this-actually-is">New Here?</a> • <a href="#why-obs-mcp">Why OBS-MCP?</a> • <a href="#features">Features</a> • <a href="docs/TOOLS.md">Tools Reference</a> • <a href="docs/ARCHITECTURE.md">Architecture</a> • <a href="#troubleshooting">Troubleshooting</a> </p>

OBS-MCP connects any MCP-compatible AI assistant to OBS Studio, giving it full control over your stream and recordings. Say "clean up my mic" or "switch to my starting soon scene" and it just happens — no clicking through menus yourself.

148 tools cover the entire obs-websocket v5 protocol — scenes, sources, the full audio mixer, filters, transitions, streaming, recording, virtual camera, replay buffer, studio mode, and output stats. On top of raw control, pipeline tools do the actual job in one call instead of making the AI hand-assemble a filter chain: clean_audio_input builds a verified Noise Gate → Noise Suppression → Compressor chain instead of guessing at OBS's internal filter parameter names, and diagnose_av_health tells you why your frames are dropping instead of handing back raw numbers.

No cloud. Nothing leaves your machine. OBS-MCP is a local WebSocket client that talks directly to OBS Studio's built-in obs-websocket server — your stream, recordings, and scene setup stay on your computer. Bring whatever AI client you already use (Claude Desktop, Claude Code, Cursor, any MCP client) — OBS-MCP handles OBS.

If this is useful to you, a star helps other people find it — that's the whole marketing budget for this project. Want to help keep it maintained? Click the Sponsor badge up top.

Works With

OBS-MCP works with any AI client that supports the Model Context Protocol:

Claude Desktop — Anthropic's desktop app
Claude Code — CLI agent
Cursor — AI code editor with MCP support
Any other MCP-compatible client

Why OBS-MCP?

Pipeline tools, not just raw API access. Most OBS automation stops at "call obs-websocket." OBS-MCP goes further — clean_audio_input, diagnose_av_health, and other pipelines encode the actual expertise (the right filter chain order, what a dropped-frame stat actually means) so the AI gets it right instead of guessing at parameter names.
100% local. No cloud calls, no API keys, nothing leaves your machine — OBS-MCP talks to OBS Studio's own built-in WebSocket server on disk-and-loopback only.
Full protocol coverage. All of obs-websocket v5 is exposed — scenes, audio mixer, filters, transitions, streaming, recording, virtual camera, replay buffer, studio mode — not a curated subset.
Composable with companion tools. Pairs with Reaper-MCP and Audacity-MCP if your stream setup also touches music production or audio cleanup — same AI conversation, different tool for each job.

New here? What this actually is

If you've never used Claude Desktop or heard of "MCP" before, here's the whole idea in plain terms:

Claude Desktop is Anthropic's free AI chat app (like ChatGPT, but made by Anthropic) — you download it, sign in, and type messages to it like a chatbot.
MCP (Model Context Protocol) is a plug-in system that lets that chat app actually do things on your computer, not just talk. Without MCP, Claude can only give you instructions ("go to Tools menu, click..."). With MCP, Claude can just do it directly.
OBS-MCP is the plug-in for OBS Studio specifically. Once it's installed, you can type things like "clean up my mic" or "switch to my starting soon scene" into Claude, and it actually happens in OBS — no clicking through menus yourself.

You don't need to know any code to use this. The installer below handles everything except two things only you can do: telling OBS to allow the connection, and telling your AI app to use this plug-in. Both are explained step by step.

Quick Start

1. Get OBS-MCP

Option A: Click the green Code button above → Download ZIP → extract it to a folder somewhere easy to find (like your Desktop) — works with nothing pre-installed, easiest on a brand new machine.

Option B: Clone with git (lets you git pull for updates later):

A fresh Windows install doesn't ship with git — check first:

git --version

If that says "not recognized", install it, then close and reopen your terminal:

winget install --id Git.Git -e --source winget

(winget itself ships with Windows 11 and up-to-date Windows 10. If winget isn't found either, grab the installer directly from git-scm.com.)

macOS/Linux almost always have git already — git --version to check, or brew install git / sudo apt install git if not.

git clone https://github.com/xDarkzx/OBS_MCP.git

2. Run the installer (installs OBS-MCP and sets up your AI client, automatically)

Windows: either double-click install.bat in File Explorer, or — if you're already in a terminal from the git clone step above — just keep going in the same PowerShell/Command Prompt window (copy-paste both lines):

cd OBS_MCP
.\install.bat

macOS / Linux:

cd OBS_MCP
bash install.sh

The installer checks you have Python (offers to install it if not), installs the obs-mcp command, and — if you say yes when it asks — automatically writes the config for Claude Desktop and/or LM Studio. No manual JSON editing required. Once it finishes, skip straight to step 3.

<details> <summary>I don't use Claude Desktop or LM Studio, or want to install manually</summary>

Don't even want to clone the repo? OBS-MCP is on PyPI:

pip install obs-mcp

(or pip install -e . from inside the folder if you already have the repo cloned/extracted). Either way, this puts an obs-mcp command on your PATH — find where it landed with where obs-mcp (Windows) or which obs-mcp (macOS/Linux) if you ever need the exact file path. Add this to your client's MCP config:

{
  "mcpServers": {
    "obs": {
      "command": "obs-mcp",
      "env": {
        "OBS_HOST": "localhost",
        "OBS_PORT": "4455",
        "OBS_PASSWORD": "your_password_here"
      }
    }
  }
}

Or for zero footprint (same idea as npx in Node.js — nothing stays installed, uvx runs it fresh each time from its own cache): since there's no permanent obs-mcp binary in this case, point the config at uvx itself instead:

{
  "mcpServers": {
    "obs": {
      "command": "uvx",
      "args": ["obs-mcp"],
      "env": {
        "OBS_HOST": "localhost",
        "OBS_PORT": "4455",
        "OBS_PASSWORD": "your_password_here"
      }
    }
  }
}

If you'd rather not install anything at all, point your client straight at the source file instead of a command — obs_mcp/main.py inside the folder you cloned/extracted is the actual MCP server entry point:

{
  "mcpServers": {
    "obs": {
      "command": "python",
      "args": ["-m", "obs_mcp.main"],
      "cwd": "/absolute/path/to/the/OBS_MCP/folder/you/extracted",
      "env": {
        "OBS_HOST": "localhost",
        "OBS_PORT": "4455",
        "OBS_PASSWORD": "your_password_here"
      }
    }
  }
}

Either way: leave OBS_PASSWORD empty ("") if you didn't set one in OBS. If your password has a " or \ in it, escape it for JSON (\" / \\) — everything else can go in as-is. Check your client's own MCP documentation for where its config file lives. Full detail, including exact config-file paths per OS: Installation Guide.

</details>

3. Enable the WebSocket server in OBS

This is the one thing the installer genuinely can't do for you — OBS itself has to allow the connection.

OBS Studio ships this built in since v28 — there's nothing to download or install for this part.

Open OBS Studio.
Tools → WebSocket Server Settings.
Check Enable WebSocket server.
Note the Server Port (default 4455, you usually don't need to change this).

No password set yet? Leave it blank — that's fine for a normal single-PC setup.

Already have a password (from a Stream Deck integration, chatbot, or earlier setup)? Don't retype it from memory — click Show Connect Info in that same settings window, which reveals the exact password OBS has stored.

Full walkthrough with screenshots-worth of detail if you get stuck: Installation Guide.

4. Talk to your AI

Restart Claude Desktop if it was already open, then just talk to it normally — for example:

"What OBS scenes do I have?"
"Clean up my mic audio"
"Why are my frames dropping?"
"Switch to my Starting Soon scene"

If OBS is running with the WebSocket server enabled, it just works — no special syntax, ask like you'd ask a person.

Features

| Category | Tools | What it does | |----------|:-----:|---------------| | General | 9 | Version/stats, hotkeys, custom events, vendor requests, persistent data storage | | Config | 15 | Scene collections, profiles, video/canvas settings, stream service destination, record directory | | Sources | 3 | Active-state check and screenshots — works for both inputs and scenes | | Scenes | 12 | List/create/remove/rename scenes, program/preview control, per-scene transition overrides, canvases, groups | | Inputs & Audio | 28 | Create/configure inputs; full mixer — mute, volume, balance, sync offset, monitor type, audio track routing, deinterlace mode | | Transitions | 9 | List/set transitions, duration, settings, T-bar scrubbing, trigger transitions (including studio mode) | | Filters | 10 | Full CRUD on source filter chains — audio and video effects, any order | | Scene Items | 17 | Transform (position/scale/crop), enabled/locked state, z-order, blend mode | | Outputs | 17 | Virtual camera, replay buffer, and any generic named output | | Stream & Record | 14 | Start/stop/toggle, captions, pause/resume, file splitting, chapter markers | | Media | 4 | Playback control for media sources — status, seek, play/pause/stop/restart/next/previous | | UI | 8 | Studio mode, property/filter/interact dialogs, monitor list, projectors | | **