# streamlabs-mcp

An [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server that gives AI assistants direct control over **Streamlabs Desktop** — switch scenes, show/hide sources, adjust audio, start/stop streaming or recording, manage studio mode, and more.

It talks to Streamlabs Desktop's own local **Remote Control API** (the same one used by Streamlabs' official mobile remote-control app), so no unofficial hacks or screen automation are involved.

This is **not a Claude-only tool**. MCP is an open, model-agnostic protocol, so this server works with **any** MCP-compatible client — Claude Desktop, Claude Code, Cursor, or anything else that can spawn a local stdio MCP server.

> **Disclaimer:** This is an independent, community project. It is not made or endorsed by Streamlabs. Use at your own risk — some tools (e.g. `streamlabs_toggle_streaming`) can start/stop your live stream, so give your AI assistant clear instructions about when it's allowed to use them.

## Features

- 59 tools covering scenes, scene items (position/scale/rotation/crop), sources, audio, streaming/recording, replay buffer, studio mode, scene collections, notifications, and performance stats.
- Pure stdio MCP server — no cloud relay, no external service. Your assistant talks directly to Streamlabs Desktop over your own machine's loopback connection.
- Zero configuration beyond a single token.

## Prerequisites

- [Streamlabs Desktop](https://streamlabs.com/streamlabs-desktop) installed and running on the same machine.
- [Node.js](https://nodejs.org) 18 or newer.
- An MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.).

## 1. Enable Remote Control in Streamlabs Desktop

1. Open Streamlabs Desktop.
2. Go to **Settings -> Remote Control**.
3. Click the QR code, then **Show details**.
4. Copy the **token** shown there. Treat this like a password — anyone with it can control your stream.

## 2. Install

```bash
git clone https://github.com/AhmadTariq1337/streamlabs-mcp.git
cd streamlabs-mcp
npm install
```

## 3. Configure your MCP client

This server reads two environment variables:

| Variable | Required | Default | Description |
|---|---|---|---|
| `STREAMLABS_TOKEN` | Yes | — | The token from step 1. |
| `STREAMLABS_HOST` | No | `127.0.0.1:59650` | Host:port of the Streamlabs Desktop API. |

Point your MCP client at `node <path-to-this-folder>/index.js` with `STREAMLABS_TOKEN` set. Examples below.

### Claude Desktop / Claude Code

Add to your MCP config (Claude Desktop: **Settings -> Developer -> Edit Config**; Claude Code: your project or user `mcp.json`):

```json
{
  "mcpServers": {
    "streamlabs": {
      "command": "node",
      "args": ["/absolute/path/to/streamlabs-mcp/index.js"],
      "env": {
        "STREAMLABS_TOKEN": "paste-your-token-here"
      }
    }
  }
}
```

Restart your client afterward.

### Cursor

Same shape, in Cursor's `mcp.json`:

```json
{
  "mcpServers": {
    "streamlabs": {
      "command": "node",
      "args": ["/absolute/path/to/streamlabs-mcp/index.js"],
      "env": {
        "STREAMLABS_TOKEN": "paste-your-token-here"
      }
    }
  }
}
```

### Any other MCP client

This is a standard stdio MCP server — configure your client to run:

```
node /absolute/path/to/streamlabs-mcp/index.js
```

with `STREAMLABS_TOKEN` (and optionally `STREAMLABS_HOST`) set in its environment. That's all any MCP client needs.

## 4. Test it

With Streamlabs Desktop running, ask your assistant something like *"list my Streamlabs scenes"* or *"what's my current streaming status?"*.

## Tool reference

### Scenes
| Tool | Description |
|---|---|
| `streamlabs_list_scenes` | List all scenes in the current scene collection. |
| `streamlabs_get_scene` | Get a specific scene by id. |
| `streamlabs_get_active_scene` | Get the currently active scene and its items. |
| `streamlabs_switch_scene` | Switch to a different scene. |
| `streamlabs_create_scene` | Create a new empty scene. |
| `streamlabs_remove_scene` | Delete a scene. |
| `streamlabs_rename_scene` | Rename a scene. |
| `streamlabs_clear_scene` | Remove all items from a scene. |
| `streamlabs_add_source_to_scene` | Add an existing source to a scene. |
| `streamlabs_create_and_add_source` | Create a new source and add it to a scene in one step. |

### Scene items
| Tool | Description |
|---|---|
| `streamlabs_set_scene_item_visibility` | Show or hide a scene item. |
| `streamlabs_remove_scene_item` | Remove an item from a scene. |
| `streamlabs_set_scene_item_transform` | Set position/scale/rotation/crop. |
| `streamlabs_set_scene_item_scale` | Set scale around an origin point. |
| `streamlabs_reset_scene_item_transform` | Reset transform to default. |
| `streamlabs_flip_scene_item_x` / `_y` | Flip an item horizontally/vertically. |
| `streamlabs_rotate_scene_item` | Rotate by a number of degrees. |
| `streamlabs_center_scene_item` | Center an item on the canvas. |
| `streamlabs_fit_scene_item_to_screen` | Fit to canvas, preserving aspect ratio. |
| `streamlabs_stretch_scene_item_to_screen` | Stretch to fill the canvas. |

### Sources
| Tool | Description |
|---|---|
| `streamlabs_list_sources` | List all sources. |
| `streamlabs_get_source` | Get a source by id. |
| `streamlabs_get_sources_by_name` | Find sources by display name. |
| `streamlabs_create_source` | Create a source without adding it to a scene. |
| `streamlabs_remove_source` | Delete a source everywhere it's used. |
| `streamlabs_list_available_source_types` | List source types this system can create. |
| `streamlabs_get_source_settings` | Get a source's settings. |
| `streamlabs_update_source_settings` | Update a source's settings (URL, text, etc). |
| `streamlabs_rename_source` | Rename a source. |
| `streamlabs_duplicate_source` | Duplicate a source. |
| `streamlabs_refresh_source` | Reload a source (e.g. a browser source). |

### Audio
| Tool | Description |
|---|---|
| `streamlabs_list_audio_sources` | Audio sources for the current scene. |
| `streamlabs_list_all_audio_sources` | Every audio source, all scenes. |
| `streamlabs_list_audio_sources_for_scene` | Audio sources for a given scene. |
| `streamlabs_set_source_muted` | Mute/unmute an audio source. |
| `streamlabs_set_source_volume` | Set volume (0.0–1.0). |

### Streaming / recording
| Tool | Description |
|---|---|
| `streamlabs_get_streaming_status` | Current streaming/recording state. |
| `streamlabs_toggle_streaming` | Start/stop the live stream. |
| `streamlabs_toggle_recording` | Start/stop local recording. |
| `streamlabs_start_replay_buffer` / `streamlabs_stop_replay_buffer` | Control the replay buffer. |
| `streamlabs_save_replay` | Save the current instant replay. |

### Studio mode
| Tool | Description |
|---|---|
| `streamlabs_get_studio_mode_status` | Current studio mode state. |
| `streamlabs_enable_studio_mode` / `streamlabs_disable_studio_mode` | Toggle studio mode. |
| `streamlabs_execute_studio_mode_transition` | Push the previewed scene live. |

### Scene collections
| Tool | Description |
|---|---|
| `streamlabs_list_scene_collections` | List saved scene collections. |
| `streamlabs_get_active_scene_collection` | Currently loaded collection. |
| `streamlabs_load_scene_collection` | Switch collections. |
| `streamlabs_create_scene_collection` | Create a new collection. |
| `streamlabs_delete_scene_collection` | Delete a collection. |
| `streamlabs_rename_scene_collection` | Rename a collection. |

### Notifications & performance
| Tool | Description |
|---|---|
| `streamlabs_list_notifications` | List in-app notifications. |
| `streamlabs_mark_notification_read` / `streamlabs_mark_all_notifications_read` | Mark notifications read. |
| `streamlabs_push_notification` | Push a new notification. |
| `streamlabs_show_notifications_panel` | Open the notifications panel. |
| `streamlabs_get_performance_stats` | CPU, FPS, dropped frames, bandwidth, disk space. |

## Troubleshooting

- **Connection times out**: Streamlabs Desktop must be running with Remote Control enabled (step 1). Check that Windows Firewall isn't blocking Node from opening a local connection to the port.
- **Auth error**: the token may have been regenerated since you copied it — grab the current one from Settings -> Remote Control.
- **Different port**: set `STREAMLABS_HOST` if your Streamlabs Desktop build listens elsewhere, e.g. `"127.0.0.1:PORT"`.
- **A specific tool errors on a newer Streamlabs Desktop version**: the underlying API is Streamlabs' internal service layer and isn't a versioned public contract, so a method name can occasionally change between releases. Open an issue with the error message, or send a PR.

## Security note

`STREAMLABS_TOKEN` grants full remote control of your stream (including going live). Keep it out of version control — `.gitignore` already excludes `.env`. Use `.env.example` as a template.

## Contributing

Issues and PRs welcome. If you add a tool, please also add it to the reference table above.

## License

[MIT](./LICENSE)