DualStream MCP Server

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 app

What you can ask for

Once 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.

Before you start

You need three things installed. Each is a normal download-and-run installer:

1. The DualStream desktop app (Windows or macOS): the studio this server controls.
2. 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.
3. An AI assistant that supports MCP, such as Claude Desktop or the Claude CLI.

Installation

Step 1: Get this project onto your computer

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.)

Step 2: Build it

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 build

Each prints some text and returns to the prompt. That's it; the server is built.

Step 3: Tell your assistant about it

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\DualStream-MCP). 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\\DualStream-MCP\\dist\\index.js"]
    }
  }
}

Claude CLI: one command (replace the path with yours):

claude mcp add dualstream -- node "C:\Users\you\Documents\DualStream-MCP\dist\index.js"

Any other MCP client works the same way: run node <folder>/dist/index.js as a stdio server.

Step 4: Say hello

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.

First connection and security

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.

Tools

Scenes and clips

Tool	Description
get_scenes	List all scenes.
get_active_scene	The scene currently live, or null.
activate_scene	Switch the live output to a scene, by id or name.
get_state_snapshot	Full scene state in one call; the resync anchor.
trigger_clip	Save the last N seconds as a clip pair (a horizontal and a vertical file).
get_recent_events	Poll buffered app events (scene changes, clips saved, relayed stream events) with sequence numbers.
get_connection_status	Whether the app is reachable, app version, and this connection's approval state.
wait_for_event	Block until the next event arrives (or return buffered ones immediately). The live-reaction primitive behind automations.

Scene composition

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
list_devices	Enumerate cameras, capture cards, displays, windows, and audio inputs, ready to add.
create_scene	Create a new scene, optionally switching to it.
list_sources	The sources in a scene with their per-canvas layout.
add_source	Add a camera, display, window, or audio device to a scene.
remove_source	Remove a source.
set_source_transform	Position and size a source, per canvas.
set_source_crop	Crop pixels off a source's edges.
set_source_shape	Mask a source to a circle, squircle, or rounded rectangle.
set_source_effects	Apply a border, shadow, glow, or blur.
set_source_order	Change layer order (front, back, up, down).

Recipes

Recipes are DualStream's shareable scene templates: a background plus positioned sources for both canvases, saved as JSON on disk.

Tool	Description
list_recipes	List installed recipes.
apply_recipe	Build a live scene from a recipe, or apply one into an existing scene.
save_recipe	Author a brand-new recipe from a manifest and save it to your library.

Widgets

Tool	Description
get_widget_settings	Read the current settings of the alert box, chat box, goal tracker, or prediction tracker.
update_widget_settings	Apply new settings. Reads and writes use the same shape, so an assistant can fetch, modify, and send back.

AI Card

Tool	Description
post_card	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

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
list_automations	Your stored automations and their standing instructions.
save_automation	Create or update an automation; matching events start relaying immediately.
delete_automation	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."

Configuration

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
DUALSTREAM_MCP_CLIENT_NAME	The name shown in DualStream's consent prompt and client list	claude-mcp
DUALSTREAM_CONTROL_PASSWORD	Fallback credential if the app does not publish a pairing token	unset
DUALSTREAM_WS_CONTROL_FILE	Override the discovery file path	platform config dir
DUALSTREAM_MCP_LOG_LEVEL	error, warn, info, or debug	info

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.

Troubleshooting

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.

Design notes

• 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.

Development

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.

About DualStream

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.

License

Apache-2.0