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 zodThese 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/mcpCursor
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
uuid | string | Yes | Action UUID to capture |
column | number | Yes | Grid column position |
row | number | Yes | Grid row position |
count | number | No | Number 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.pngdialPreview
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.pngqueryLogs
Searches captured console output. Supports case-insensitive substring matching and /regex/ patterns.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | No | Plain text or /regex/ pattern |
actionUuid | string | No | Filter to logs from a specific action UUID |
limit | number | No | Max 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
uuid | string | Yes | Action UUID of the key |
column | number | Yes | Grid column position |
row | number | Yes | Grid 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
uuid | string | Yes | Action UUID of the dial/encoder |
column | number | Yes | Grid column position |
row | number | Yes | Grid row position |
ticks | number | Yes | Rotation 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
uuid | string | Yes | Action UUID of the dial/encoder |
column | number | Yes | Grid column position |
row | number | Yes | Grid 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
uuid | string | Yes | Action UUID of any encoder on the target device |
column | number | Yes | Grid column position of the encoder |
row | number | Yes | Grid row position |
tapX | number | Yes | X position within the touch segment (0-199) |
tapY | number | Yes | Y position within the touch segment (0-99) |
hold | boolean | No | Whether 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
- When
mcp: trueis set, the plugin starts an HTTP server onlocalhost(port range 39500 -- 39599). The port is derived from the plugin UUID via a djb2 hash. - The server uses the Streamable HTTP transport from
@modelcontextprotocol/sdk, which supports both request/response and SSE streaming. - Agents connect by sending MCP protocol messages to
POST /mcp. - Console output is captured into a bounded ring buffer (500 entries) for log queries.
- 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.