@fcannizzaro/streamdeck-react

MCP Server

Expose a Model Context Protocol server so AI agents can inspect and interact with your running Stream Deck plugin.

Overview

When enabled, the plugin starts a local Model Context Protocol (MCP) server that AI agents (Cursor, Claude Desktop, custom tooling) can connect to. The server exposes tools for listing visible actions, capturing key/dial/touch strip screenshots, querying console logs, and simulating hardware input (key presses, dial rotations, touch taps) -- everything an agent needs to understand and interact with your plugin at runtime.

The MCP server follows the same patterns as the DevTools: it is development-only, uses a deterministic port derived from the plugin UUID, and is automatically stripped from production builds.

Enabling the MCP Server

Set mcp: true in your createPlugin configuration:

import { createPlugin } from "@fcannizzaro/streamdeck-react";

const plugin = createPlugin({
  mcp: true,
  fonts: [
    // ...your fonts
  ],
  actions: [
    // ...your actions
  ],
});

The port is derived deterministically from the plugin UUID (range 39500 -- 39599), so the same plugin always uses the same port. To use a specific port instead:

const plugin = createPlugin({
  mcp: { port: 39550 },
  // ...
});

Installing the MCP SDK

The MCP server depends on @modelcontextprotocol/sdk and zod, which are optional peer dependencies. Install them when you enable MCP:

bun add -D @modelcontextprotocol/sdk zod

These packages are only needed during development and are stripped from production builds.

Connecting an Agent

Once the plugin is running with mcp: true, you'll see a log line like:

[@fcannizzaro/streamdeck-react] MCP server listening on http://127.0.0.1:39523/mcp

Cursor

Add the server to your .cursor/mcp.json:

{
  "mcpServers": {
    "streamdeck": {
      "url": "http://127.0.0.1:39523/mcp"
    }
  }
}

Claude Desktop

Add the server to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "streamdeck": {
      "url": "http://127.0.0.1:39523/mcp"
    }
  }
}

Health Check

The server exposes a GET /health endpoint for discovery:

curl http://127.0.0.1:39523/health
# {"status":"ok","protocol":"mcp"}

Available Tools

The MCP server registers nine tools organized in two categories:

Inspection Tools

listKeys

Lists all visible Stream Deck actions with their UUID, surface type, grid coordinates, and device info.

// Example response
[
  {
    "actionId": "abc123",
    "actionUuid": "com.example.plugin.counter",
    "surface": "key",
    "coordinates": { "column": 0, "row": 1 },
    "deviceId": "device-1",
    "deviceName": "Stream Deck XL"
  }
]

keyPreview

Captures screenshot(s) of a specific key and saves them as PNG files.

ParameterTypeRequiredDescription
uuidstringYesAction UUID to capture
columnnumberYesGrid column position
rownumberYesGrid row position
countnumberNoNumber of frames to capture (1-10, default 1)

Screenshots are written to screenshot-mcp/ in the project root and the tool returns the relative file path(s). Multiple frames are captured with ~100ms intervals -- useful for inspecting animations.

Screenshot saved: screenshot-mcp/key-0-1-1.png

dialPreview

Same as keyPreview but for encoder dial surfaces (200x100). Parameters are identical.

touchStripPreview

Captures screenshot(s) of a touch strip. Provide the UUID of any encoder action on the target device to locate the strip. Each segment is saved as a separate PNG file.

Screenshots saved (4 segments):
screenshot-mcp/touchstrip-seg0-1.png
screenshot-mcp/touchstrip-seg1-1.png
screenshot-mcp/touchstrip-seg2-1.png
screenshot-mcp/touchstrip-seg3-1.png

queryLogs

Searches captured console output. Supports case-insensitive substring matching and /regex/ patterns.

ParameterTypeRequiredDescription
querystringNoPlain text or /regex/ pattern
actionUuidstringNoFilter to logs from a specific action UUID
limitnumberNoMax entries to return (default 50, max 200)

Results are returned newest-first.

Interaction Tools

Interaction tools simulate hardware input by dispatching events through the same registry.dispatch() path used by real SDK events. The component hooks (useKeyDown, useDialRotate, useTouchTap, etc.) cannot distinguish simulated events from physical ones.

All interaction tools identify the target action using uuid, column, and row -- the same coordinates returned by listKeys.

pressKey

Simulates a full key press cycle: dispatches keyDown, waits 50ms, then dispatches keyUp. Only works on key surface actions.

ParameterTypeRequiredDescription
uuidstringYesAction UUID of the key
columnnumberYesGrid column position
rownumberYesGrid row position
Key pressed: com.example.plugin.counter at (0, 1). keyDown + keyUp dispatched.

rotateDial

Simulates an encoder dial rotation. Works on both standalone dial surfaces and touch strip encoders.

ParameterTypeRequiredDescription
uuidstringYesAction UUID of the dial/encoder
columnnumberYesGrid column position
rownumberYesGrid row position
ticksnumberYesRotation ticks (positive = clockwise, negative = counterclockwise)
Dial rotated: com.example.plugin.volume at (0, 0). 3 tick(s) clockwise.

pressDial

Simulates a full dial press cycle: dispatches dialDown, waits 50ms, then dispatches dialUp. Works on both standalone dial surfaces and touch strip encoders.

ParameterTypeRequiredDescription
uuidstringYesAction UUID of the dial/encoder
columnnumberYesGrid column position
rownumberYesGrid row position
Dial pressed: com.example.plugin.volume at (0, 0). dialDown + dialUp dispatched.

tapTouch

Simulates a touch tap on an encoder surface. Coordinates are relative to the encoder segment (0-199 x 0-99). For touch strip actions, the coordinates are automatically remapped to absolute strip position.

ParameterTypeRequiredDescription
uuidstringYesAction UUID of any encoder on the target device
columnnumberYesGrid column position of the encoder
rownumberYesGrid row position
tapXnumberYesX position within the touch segment (0-199)
tapYnumberYesY position within the touch segment (0-99)
holdbooleanNoWhether this is a long press (default false)
Touch tapped: com.example.plugin.eq at (1, 0), position (100, 50).

Simulated event payloads use empty settings ({}). Components should use the useSettings() hook for settings access rather than reading payload.settings.

Screenshots Directory

All preview tools write PNG files to the screenshot-mcp/ directory in your project root. The directory is created automatically on the first capture.

Files follow a deterministic naming convention:

  • Keys: key-{column}-{row}-{frame}.png
  • Dials: dial-{column}-{row}-{frame}.png
  • Touch strip segments: touchstrip-seg{column}-{frame}.png

Add screenshot-mcp/ to your .gitignore:

screenshot-mcp/

How It Works

  1. When mcp: true is set, the plugin starts an HTTP server on localhost (port range 39500 -- 39599). The port is derived from the plugin UUID via a djb2 hash.
  2. The server uses the Streamable HTTP transport from @modelcontextprotocol/sdk, which supports both request/response and SSE streaming.
  3. Agents connect by sending MCP protocol messages to POST /mcp.
  4. Console output is captured into a bounded ring buffer (500 entries) for log queries.
  5. All MCP code is automatically stripped from production builds -- there is zero overhead in release bundles.

Using with DevTools

MCP and DevTools can run simultaneously. They use separate port ranges (MCP: 39500-39599, DevTools: 39400-39499) to avoid collisions:

const plugin = createPlugin({
  devtools: true,
  mcp: true,
  // ...
});

Both features independently intercept console output. DevTools serializes arguments for the SSE bridge, while MCP formats flat strings for the log store. Neither interferes with the other.

Production Stripping

Like DevTools, the MCP server is automatically removed from production builds. The Vite plugin replaces the dynamic import("./mcp/index.js") with a no-op module when NODE_ENV=production (non-watch builds). No manual configuration is needed.

On this page