An MCP server for OBS
Configuration
View docs{
"mcpServers": {
"royshil-obs-mcp": {
"command": "npx",
"args": [
"-y",
"obs-mcp@latest"
],
"env": {
"OBS_WEBSOCKET_URL": "ws://localhost:4455",
"OBS_WEBSOCKET_PASSWORD": "<password_from_obs>"
}
}
}
}This MCP Server lets you control OBS Studio through the OBS WebSocket protocol using a lightweight, configurable command interface. It exposes a set of tools to manage scenes, sources, streaming, recording, and transitions, all accessible from an MCP client to automate and streamline your OBS workflows.
To control OBS with your MCP client, first ensure OBS Studio is running and the WebSocket server is enabled (Tools > WebSocket Server Settings). Note and save the WebSocket password you set there.
Next, set the required environment variable for the OBS WebSocket password in your environment so the MCP server can authenticate with OBS. You will configure this in the MCP client setup screen as shown below.
Add the MCP server configuration for OBS in your MCP client. The configuration defines how to start the local MCP server process that connects to OBS. You have two equivalent local startup approaches you can use depending on your preference. Run either approach from your MCP client setup screen.
Option 1: Start via NPX (download-and-run) approach. This uses the latest OBS MCP package without requiring a local install. You specify the command and arguments, and provide the OBS password via environment variables.
Option 2: Start via Node from a built distribution. This runs a locally built index file after you build the project. You still supply the OBS password via environment variables.
Prerequisites you need before proceeding:
Step-by-step setup to configure the OBS MCP server in your MCP client
{
"mcpServers": {
"obs_npx": {
"command": "npx",
"args": ["-y", "obs-mcp@latest"],
"env": {
"OBS_WEBSOCKET_PASSWORD": "<password_from_obs>"
}
},
"obs_node": {
"command": "node",
"args": ["<obs-mcp_root>/build/index.js"],
"env": {
"OBS_WEBSOCKET_PASSWORD": "<password_from_obs>"
}
}
}
}Environment variables control access to OBS WebSocket. Set OBS_WEBSOCKET_PASSWORD to the password configured in OBS. You can also specify OBS_WEBSOCKET_URL to point to a non-default URL if your OBS WebSocket server is hosted remotely or on a different port. The default WebSocket URL is ws://localhost:4455.
If you run the NPX approach, your MCP client will fetch the latest obs-mcp package on startup. If you run the built Node approach, you must first build the package (npm run build) and then start from the built index.js file (npm run start or direct node command as shown).
Best practices: keep OBS WebSocket password secret and restrict access to the MCP client machine. If you encounter connection issues, verify that OBS WebSocket is enabled, the password matches, and that no firewall blocks the WebSocket port.
Common issues include: incorrect WebSocket password, WebSocket server disabled in OBS, or mismatched URL/port. Double-check Tools > WebSocket Server Settings and ensure the password in your MCP client configuration matches exactly.
Notes: the OBS MCP server exposes a range of tools organized by category, including general controls, scene management, source and item manipulation, streaming/recording, and transitions. You can tailor your MCP client setup to expose just the tools you need for your workflow.
Provide the MCP server version and build status to help you track compatibility.
Show runtime and usage statistics for monitoring performance and activity.
Expose hotkey management to trigger OBS actions quickly.
Toggle and manage studio mode for preview and program scenes.
List scenes, switch scenes, create or remove scenes.
Manage sources and their settings, adjust audio levels, mute/unmute.
Control items within scenes, including position and visibility.
Start/stop streaming, recording, and virtual camera.
Set transitions, durations, and trigger transitions.