DualStream MCP Server is a local bridge that lets an AI assistant operate the DualStream streaming studio (scene switching, layout, widgets, clips, and automations) over MCP, controlling both desktop (16:9) and mobile (9:16) canvases via a loopback connection to the desktop app.
Scenes & clips: list, create, activate, and resync scenes; switch live output; capture instant-replay clip pairs (H+V).
Scene composition: enumerate devices; add/remove cameras, displays, windows, and audio; position, crop, mask, effect, order, show/hide, and mute sources per canvas.
Recipes: list, apply (create scene from template or merge into existing), and author reusable scene templates with per-canvas layouts.
Widgets: read and update settings for alerts, chat, goal, and prediction widgets, round-tripping full settings objects.
AI Cards: post titled, short viewer-facing cards through the alert system (opt-in alert type).
Automations: list, create/update, and delete stream-event automations that pair triggers (raids, cheers, follows) with standing AI instructions.
Live reactions & events: poll buffered events or block (wait_for_event) to react in real time to stream activity.
Status & diagnostics: check connection/consent state, app reachability, and version; gracefully handle consent_pending, app_not_running, and auth errors.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@DualStream MCP Server Switch to my BRB scene"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Our first Open Source project! The official Model Context Protocol server for DualStream, the streaming studio that produces desktop (16:9) and mobile (9:16) streams simultaneously from a single pipeline.
This server lets AI assistants like Claude operate your DualStream studio: switch scenes, save instant-replay clips, build entire scene layouts from scratch, restyle your alerts and widgets, and react to what happens on stream. Everything runs locally on your machine, with your explicit approval, and every change renders on both your desktop and mobile canvases.
AI assistant (Claude Code, Claude Desktop, or any MCP client)
| MCP over stdio
v
DualStream MCP server (this package)
| JSON-RPC over WebSocket, 127.0.0.1 only
v
DualStream desktop appOnce connected, you talk to your assistant in plain language:
"Switch to my BRB scene"
"Clip the last 30 seconds"
"Create a scene called MAIN with my webcam in the bottom right, cropped to a circle, and my primary display fullscreen behind it"
"Make me a starting-soon scene for a charity stream in my brand colors, both canvases"
"Restyle my alerts to match this palette"
"Move the camera up a bit and give it a soft shadow"
The assistant discovers your actual hardware (cameras, displays, windows, microphones), composes layouts for the desktop and mobile canvases independently, and iterates with you until it looks right.
Related MCP server: WAVE MCP Server
You need three things installed. Each is a normal download-and-run installer:
The DualStream desktop app (Windows or macOS): the studio this server controls.
Node.js: pick the big green LTS button (version 22 or newer). This is the runtime that runs the server; you won't interact with it directly.
An AI assistant that supports MCP, such as Claude Desktop or the Claude CLI.
Click the green Code button at the top of this GitHub page and choose Download ZIP, then unzip it somewhere you'll remember, for example your Documents folder. (If you're comfortable with git, git clone works too.)
Open a terminal in the unzipped folder:
Windows: open the folder in File Explorer, click the address bar, type cmd, and press Enter.
macOS: right-click the folder and choose New Terminal at Folder (or drag the folder onto Terminal).
Then run these two commands, one after the other:
npm install
npm run buildEach prints some text and returns to the prompt. That's it; the server is built.
You need the full path to the folder from Step 1. In Windows File Explorer, click the address bar and copy it (it looks like C:\Users\you\Documents\DualStreamMCP). On macOS, right-click the folder, hold Option, and choose Copy as Pathname.
Claude Desktop: open Settings → Developer → Edit Config, and add this (replace the path with yours; on Windows, use double backslashes as shown):
{
"mcpServers": {
"dualstream": {
"command": "node",
"args": ["C:\\Users\\you\\Documents\\DualStreamMCP\\dist\\index.js"]
}
}
}Claude CLI: one command (replace the path with yours):
claude mcp add dualstream -- node "C:\Users\you\Documents\DualStreamMCP\dist\index.js"Any other MCP client works the same way: run node <folder>/dist/index.js as a stdio server.
Restart your assistant, make sure DualStream is running, and ask: "What scene am I live on in DualStream?" The first time, DualStream will pop up an approval prompt; that's the security model working (see below). Approve it, and you're done.
The DualStream app runs a small control server bound to 127.0.0.1 only. Nothing is reachable from the network, and this MCP server must run on the same machine as the app. There is no cloud component: the intelligence is whatever AI assistant you connect, and your stream never leaves your control.
Pairing is automatic. The app publishes a pairing token in its config directory, and this server picks it up on its own; you never type a password. The first time an assistant connects, DualStream shows a consent prompt naming the client. You choose Allow, Always allow, or Deny. Until you approve, the connection can't do anything. You can see every connected client, disconnect any of them, and revoke remembered approvals at any time under Settings, General, External Control in the app.
If you deny a connection, the server closes it. If you reset the pairing token in the app's settings, every connected client is disconnected and must re-pair.
Tool | Description |
| List all scenes. |
| The scene currently live, or null. |
| Switch the live output to a scene, by id or name. |
| Full scene state in one call; the resync anchor. |
| Save the last N seconds as a clip pair (a horizontal and a vertical file). |
| Poll buffered app events (scene changes, clips saved, relayed stream events) with sequence numbers. |
| Whether the app is reachable, app version, and this connection's approval state. |
| Block until the next event arrives (or return buffered ones immediately). The live-reaction primitive behind automations. |
Build and edit scenes source by source. Layouts on the desktop (1920x1080) and mobile (1080x1920) canvases are controlled independently, so a small round facecam on desktop can be a full-width square camera on mobile.
Tool | Description |
| Enumerate cameras, capture cards, displays, windows, and audio inputs, ready to add. |
| Create a new scene, optionally switching to it. |
| The sources in a scene with their per-canvas layout. |
| Add a camera, display, window, or audio device to a scene. |
| Remove a source. |
| Position and size a source, per canvas. |
| Crop pixels off a source's edges. |
| Mask a source to a circle, squircle, or rounded rectangle. |
| Apply a border, shadow, glow, or blur. |
| Change layer order (front, back, up, down). |
Recipes are DualStream's shareable scene templates: a background plus positioned sources for both canvases, saved as JSON on disk.
Tool | Description |
| List installed recipes. |
| Build a live scene from a recipe, or apply one into an existing scene. |
| Author a brand-new recipe from a manifest and save it to your library. |
Tool | Description |
| Read the current settings of the alert box, chat box, goal tracker, or prediction tracker. |
| Apply new settings. Reads and writes use the same shape, so an assistant can fetch, modify, and send back. |
Tool | Description |
| Post a short card onto the stream (a title and optional message), rendered by the alert system with the styling you configured. The AI Card alert type is off by default; enable it in the alerts inspector to allow posting. |
Automations pair a stream-event trigger (a raid, a big cheer, a hype train ending) with a standing instruction for your assistant. When a matching event happens, DualStream relays it to the assistant with your instruction attached; the assistant composes and posts the card. Only events matching an enabled automation ever leave the app, and the assistant only listens while you have a session open. The full doc format, event vocabulary, and rehearsal flow are in contract/automations-v1.md.
Tool | Description |
| Your stored automations and their standing instructions. |
| Create or update an automation; matching events start relaying immediately. |
| Remove an automation. |
A typical live session: tell your assistant you are going live; it reads your
automations, then loops on wait_for_event; waiting costs nothing, and each
handled event is one short exchange (welcome the raiders, thank the whale,
post the card).
Tool errors are structured JSON with a retryable flag, so assistants know the difference between "try again in a second" (replay buffer still warming up, connection waiting for your approval) and "something is actually wrong."
Everything works with zero configuration when the app and this server run under the same user account. These environment variables exist for unusual setups:
Variable | Purpose | Default |
| The name shown in DualStream's consent prompt and client list |
|
| Fallback credential if the app does not publish a pairing token | unset |
| Override the discovery file path | platform config dir |
|
|
|
Discovery reads ws-control.json from the app's config directory (%APPDATA%\app.dualstream.io\ on Windows, ~/Library/Application Support/app.dualstream.io/ on macOS). The app writes this file on every start, before the control server reports ready.
Tools return app_not_running. The DualStream app isn't open, or hasn't finished starting. Launch it; the server reconnects on its own the moment the app is up.
Tools return consent_pending. The connection is waiting for you. Approve it in the consent prompt inside DualStream (or under Settings, General, External Control).
Tools return authentication_required or authentication_failed. The app has auth enabled but this server couldn't obtain the token. Make sure the app and the server run as the same user. If you recently reset the pairing token, the reconnect handles it automatically; a stale DUALSTREAM_CONTROL_PASSWORD in your environment can also cause this.
Something else is off. Call get_connection_status first; it distinguishes "app not running" from auth, consent, and protocol problems. The server logs single-line JSON to stderr; set DUALSTREAM_MCP_LOG_LEVEL=debug for detail.
Local by design. The control plane is loopback-only. A hosted or remote connector cannot reach it, and never should.
Event-driven, no timers. In-flight requests settle only on a server response or socket close, never a wall-clock timeout. Reconnection is triggered by watching the discovery file the app rewrites on start; there are no polling loops.
stdout is the protocol channel. All logging goes to stderr as single-line JSON.
Contract-pinned. Responses are validated against the vendored control contract (see contract/); an app speaking a newer protocol version fails loudly with an upgrade message rather than misbehaving quietly.
Consent is enforced server-side. The approval gate lives in the DualStream app, not in this package; a modified client gains nothing.
The contract/ directory also contains authoring references an assistant can use directly: the recipe manifest format, the scene-composition guide (including layout patterns for the mobile canvas), the automations format, and PROTOCOL.md: a full method, event, and error-code reference generated from the contract fixture.
npm run typecheck # strict TypeScript over src and tests
npm test # unit + full MCP round-trips against a wire-faithful mock of the app
npm run build # emit dist/
npm run smoke # live end-to-end against a running DualStream app
# (switches a scene and back, saves one 10-second clip pair)The mock control server in test/ implements the real wire protocol, including the pairing handshake and consent flow, with an independent implementation of the auth algorithm, so the test suite genuinely cross-checks the client.
DualStream is a streaming studio for creators who go live on desktop and mobile platforms at the same time: one pipeline, two canvases, every scene and widget rendered natively for both. Download it for Windows or macOS at dualstream.gg.
Switch DualStream's live output to another scene. Takes effect immediately on the user's live stream; call only when the user asked for a scene change. Identify the scene by scene_id (preferred, from get_scenes) or by exact scene_name (case-insensitive). Optional transition name overrides the scene's default transition.
Inputs: scene_id, scene_name, transition.
Add a source to a scene (defaults to the active scene); it appears live immediately if the scene is active. For cameras/displays/windows, pass the device_id and source_type from list_devices verbatim. The new source lands centered by default; use set_source_transform to position/size it, set_source_shape to mask it, etc. Returns the new source_id.
Inputs: name (required), source_type (required), scene_id, device_id, +1 more.
Apply a recipe to the live stream. By default this CREATES a new scene from the recipe and switches to it, taking effect immediately on the user's stream, so call only when the user asked to build/switch a scene. Pass target_scene_id to instead add the recipe's sources into an existing scene. Both canvases (H+V) are populated from the recipe.
Inputs: recipe_id (required), scene_name, target_scene_id.
Create a new empty scene. Pass activate:true to switch the live output to it immediately (call only when the user wants to build/switch to it now); otherwise it's created off-air and you can populate it, then activate_scene when ready. Returns the new scene_id to pass to add_source.
Inputs: name (required), activate.
Delete a stored automation by id. Its events stop relaying immediately.
Inputs: automation_id (required).
Return the currently active scene ({scene_id, scene_name}) or null if none.
Inputs: no named parameters.
Report whether the DualStream desktop app's control server is reachable, including app version, port, auth mode, and this connection's consent state (consent: 'pending' means the streamer must approve this client inside DualStream before other tools work). Call this first when other DualStream tools fail, to distinguish 'app not running' from real errors.
Inputs: no named parameters.
Poll buffered control events (scene_activated, scenes_changed, scene_renamed, clip_saved, stream_event, resync_required), oldest first. Pass since_seq from your last call to receive only new events; truncated=true means events were evicted and you should resync with get_state_snapshot. Timestamps are receipt times stamped by this MCP server. event.stream_event entries are platform events (follows/subs/raids/…) that matched an enabled automation; use this for catch-up ('what happened this stream?'); use wait_for_event to react live.
Inputs: limit, since_seq.
List all scenes in DualStream's active collection as {scene_id, scene_name}. scene_id is stable across rename/reorder within a collection; a collection switch invalidates ids (an event.scenes_changed with reason 'collection_switched' is emitted).
Inputs: no named parameters.
Authoritative snapshot of DualStream's scene state: every scene (scene_id + scene_name) and the active scene id. Call this to (re)sync after connecting or after an event.resync_required / event.scenes_changed event.
Inputs: no named parameters.
Read the current settings JSON for a widget in the active scene (alert box, chat box, goal tracker, or prediction tracker). Returns the exact shape update_widget_settings accepts: read it, change the fields you want, send it back. Errors with widget_not_found if the active scene has no widget of that type (alerts always exist).
Inputs: widget_type (required), format.
List the streamer's stored automations; each pairs a stream-event trigger (event types, optional platform and min_amount) with a prompt: the streamer's standing instruction for what you should do when that event arrives. Disabled automations are included but never relay events.
Inputs: no named parameters.
Enumerate capture devices available to add as sources: cameras, capture cards, virtual cameras, displays, windows, audio inputs. Each entry gives a device_id and source_type ready to pass straight to add_source. Displays include is_primary and resolution. Call this first to find, e.g., the user's webcam or primary monitor.
Inputs: kind.
List DualStream's installed recipes: reusable scene templates (a background plus positioned sources for both the 16:9 and 9:16 canvases). Optionally filter by mode. Use before apply_recipe to discover recipe ids, or before authoring to avoid duplicate names.
Inputs: mode.
List the sources in a scene (defaults to the active scene) with their ids, types, visibility, per-canvas transform, and whether each has a crop/shape/effects applied. Use to find source_ids for set_source_* calls, or to see the current layout.
Inputs: scene_id.
Post a card onto the live stream via DualStream's alert system; it renders on both canvases with the styling, position, sound, and duration the streamer configured for the AI Card alert type. You supply only the text: a title and an optional message body. Use for short, timely, viewer-facing moments (welcoming a raid, celebrating a milestone), only when the user asked for it or set up an automation. The AI Card type is OFF by default; a card_disabled error means the streamer must enable it in the alerts inspector first (they were shown a notice pointing there).
Inputs: title (required), message.
Remove a source from a scene (defaults to the active scene) by source_id.
Inputs: source_id (required), scene_id.
Create or update an automation (matched by id; id is derived from name when omitted). Only create automations the streamer asked for. The doc follows automation-v1: trigger.event_types uses canonical names ("Follow", "Raid", "Cheer", "SuperChat", …); trigger.min_amount compares against the event's amount, whose meaning is per-type (raid=viewers, cheer=bits, gift=count, resub=months). Prefer rare, high-signal events; every match wakes the AI session. Matching events start relaying immediately.
Inputs: doc (required).
Author a new recipe from a manifest and save it to the user's recipe library (does NOT change the live stream; use apply_recipe for that). A manifest is a background plus a list of sources with per-canvas geometry. The simplest useful recipe uses a color/gradient background and Text sources; no media files needed. Full field reference: contract/set-design-v1.md in this package. Shapes:
background (optional): SceneBackground, e.g. {"SolidColor":{"color":"#7C3AED"}} or {"Gradient":{"start_color":"#111","end_color":"#333","direction":"DiagonalDown"}}.
sources[]: {kind, name, settings, and geometry}. kind is PascalCase ("Text","Image",...). Geometry: absolute pixels at 1920x1080 via position{x,y}+size{w,h} and verticalPosition+verticalSize for the 9:16 canvas, OR resolution-independent positionGrid (Center, TopLeft, …) + sizePct{w,h} (percent).
A Text source's settings: {text, fontFamily, fontSize, color:"#RRGGBB", outlineEnabled, outlineColor, shadowEnabled, halignment:"center", valignment:"center", backgroundColor:"#AARRGGBB", scrollEnabled, scrollSpeed}. id/version/thumbnail are filled in automatically.
Inputs: manifest (required).
Enable, disable, or toggle an effect already configured on a source (shader-style filters like a black-and-white look). Omit 'enabled' to toggle. Only effects the streamer already applied can be toggled; the error lists what is configured. Returns the new state.
Inputs: effect (required), source_id (required), format, enabled, +1 more.
Crop pixels off a source's edges. left/right/top/bottom are absolute pixels of the SOURCE's native resolution (not the canvas). anchor controls where the retained region sits (Center, Top, …). format omitted applies to both canvases.
Inputs: source_id (required), top, left, right, +4 more.
Apply visual effects to a source. Provide any of border, shadow, glow, blur (each an object). Colors are u32 RGBA integers (0xRRGGBBAA as decimal; e.g. white=4294967295). Examples. Soft shadow: {shadow:{enabled:true,offsetX:6,offsetY:8,blur:20,opacity:0.5,color:255,inner:false}}; white border: {border:{enabled:true,width:6,color:4294967295,style:0}}; blur: {blur:{enabled:true,sigma:8}}. format omitted applies to both canvases.
Inputs: source_id (required), blur, glow, border, +3 more.
Mute, unmute, or toggle an audio-carrying source. Applies to every scene containing the source (matched by device identity), so the mute survives scene switches. Omit 'muted' to toggle. The source's saved volume is preserved. Returns the new state.
Inputs: source_id (required), muted.
Change a source's layer order. 'back' sends it behind everything (use for a background/screen added after a camera so it doesn't cover the cam); 'front' brings it above other sources (alert overlays keep their reserved top layer); 'up'/'down' move one step. New sources are added on top, so a background added last usually needs 'back'.
Inputs: position (required), source_id (required), scene_id.
Mask a source to a shape. shape='Circle' inscribes a circle (great for round webcam cams); 'RoundedRectangle' uses radius (pixels); 'RoundedRectangle9x16' for portrait; 'None' clears the mask. format omitted applies to both canvases.
Inputs: shape (required), source_id (required), format, radius, +1 more.
Set a source's position and/or size on a canvas. Coordinates are absolute pixels: the horizontal (desktop) canvas is 1920×1080, the vertical (mobile) canvas is 1080×1920. Provide any of x, y, width, height (omitted keys unchanged). ALWAYS set the two canvases SEPARATELY (format:'horizontal' then format:'vertical'); a desktop layout never maps 1:1 to mobile. Desktop examples: fullscreen bg {x:0,y:0,width:1920,height:1080}; bottom-right cam {x:1400,y:790,width:480,height:270}. MOBILE (vertical 1080×1920) is a tall portrait frame; rethink the layout, don't shrink the desktop one. Good mobile patterns: (a) CAM + SCREEN: full-width square camera at the TOP {x:0,y:0,width:1080,height:1080}, and the 16:9 screen/game below it centred in the lower band {x:0,y:1196,width:1080,height:608}. (b) CAM-ONLY (just chatting): a large cam centred {x:0,y:420,width:1080,height:1080}. (c) GAME + FACECAM: game full-width at top {x:0,y:280,width:1080,height:608}, circle facecam lower {width:300,height:300}. Fill the tall frame; avoid large empty bands.
Inputs: source_id (required), x, y, width, +3 more.
Show, hide, or toggle a source in a scene. Omit 'visible' to toggle. Applies to both canvases unless format narrows it. A source_id from another scene resolves to this scene's matching instance (same device or name). Returns the new state.
Inputs: source_id (required), format, visible, scene_id.
Save the last N seconds of the stream as a clip pair (horizontal + vertical files are saved natively). duration_sec is optional; omitted uses the user's configured default. If the replay buffer is warming up the error is marked retryable; wait for the user's go-ahead and try again.
Inputs: duration_sec.
Apply new settings to a widget in the active scene; takes effect immediately on the stream. Pass the full settings object from get_widget_settings with your changes applied (round-trip: get, modify, update). format omitted applies to both canvases. For alerts, changes also update the durable canonical template used by every scene.
Inputs: settings (required), widget_type (required), format.
Block until a control event arrives (or return immediately if matching events are already buffered past since_seq). WARNING: while this call waits, the user cannot interact with their assistant at all; the whole session is held. Only call it when the user has EXPLICITLY asked you to listen for events ("watch my stream", "wait for the next raid"). Never use it to wait for consent approval or as a convenience between steps; for those, tell the user what to do, end your turn, and retry when they respond. Live-reaction loop: pass the last_seq from your previous call, filter to ['event.stream_event'] to wake only on automation-matched platform events, act on the automation prompt in the payload, then call wait_for_event again. No timeout is applied by this server; the call resolves on the next event, or fails (retryable) if the DualStream connection drops while waiting.
Inputs: since_seq (required), events.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 30 tools
Most tools target distinct resources and actions, such as scene control, source parameters, and automations. Minor overlap exists between get_state_snapshot and get_scenes/get_active_scene, but descriptions clearly differentiate a full resync snapshot from targeted queries. set_source_effects and set_effect_enabled are related but distinct (applying vs toggling filters).
Tool names overwhelmingly follow a clear verb_noun pattern with snake_case, e.g., get_, list_, set_source_, create_, save_, delete_. The only inconsistency is mixing 'get' and 'list' for read operations (get_scenes vs list_recipes), but the pattern remains predictable overall.
At 30 tools, the set exceeds the typical well-scoped range of 3-15 tools. While each operation is distinct and serves a broad streaming application feature set, the large number is likely to overwhelm agents and increase selection error in practice.
The set covers scene creation/activation, comprehensive source manipulation, automation CRUD, and event handling. Notable gaps include scene deletion/rename, recipe update/delete, and widget enumeration, which would leave agents unable to fully manage resources without workarounds.
Control evmux live streaming studios: scenes, layers, participants, media, banners and broadcast.
Manage 24/7 live streams, media, playback queues, schedules, and multistreaming from AI assistants.
Multistream relay control: check live status, switch destinations, manage teams, generate overlays.
Query your Twitch streams, events, supporters, raids & rankings from an AI assistant via OAuth.
