streamdeck-mcp

The Stream Deck MCP server that finally treats your developer workflow seriously.

Control your Elgato Stream Deck from Claude Code with high-quality icons, full profile management, and task context aggregation from Slack, Notion, and GitHub.

Why this over other Stream Deck MCPs?

• Icons that don't look like programmer art — SVG rendered at 144×144 retina with Lucide icons, macOS app icon extraction, gradients, and badges. No more Pillow text on solid colors.
• Task context aggregation — One command pulls your current task's Slack thread, Notion doc, GitHub PR, and Figma files into a single folder on your Stream Deck. No more hunting across five tools.
• Folder-based navigation — Sub-pages you can actually create programmatically, with a working /task skill that handles the whole flow.
• Claude Code native — Built as a first-class MCP server, not a port of someone's USB control library.

Install

npm install -g streamdeck-mcp

Or clone and build:

git clone https://github.com/jxxh204/streamdeck-mcp.git
cd streamdeck-mcp
npm install
npm run build

Configure

Add to your project's .mcp.json (or Claude Code settings):

{
  "mcpServers": {
    "streamdeck": {
      "command": "streamdeck-mcp"
    }
  }
}

If you installed from source, point to the built file instead:

{
  "mcpServers": {
    "streamdeck": {
      "command": "node",
      "args": ["/path/to/streamdeck-mcp/dist/index.js"]
    }
  }
}

Quick start

After restarting Claude Code, try these in a conversation:

List my Stream Deck profiles

Create a 144x144 icon with the git-branch Lucide icon on a purple gradient,
text "main", and save it as branch-icon

Extract the Cursor app icon and make it a Stream Deck button

MCP tools

Tool	Description
streamdeck_read_profiles	List all profiles with pages and metadata
streamdeck_read_page	Read page details with button layout
streamdeck_write_page	Create or update pages with buttons
streamdeck_create_icon	Generate 144×144 PNG icons (Lucide, app icons, gradients, badges, emoji)
streamdeck_create_action	Create shell script actions for buttons
streamdeck_restart_app	Restart Stream Deck to apply changes
streamdeck_list_icons	List built-in Lucide icon names
streamdeck_manage_profile	Create, rename, delete, or duplicate profiles
streamdeck_delete_page	Delete a page from a profile
streamdeck_live_dashboard	Start/stop a live dashboard daemon

Icon examples

// Lucide icon with gradient background
{ lucide: "terminal", text: "Claude",
  bg_color: "linear-gradient(#D97706, #B45309)" }

// macOS app icon extraction (uses sips under the hood)
{ app_icon: "Docker", subtitle: "Docker",
  bg_color: "linear-gradient(#2496ED, #1D7AC4)" }

// Notification badge
{ lucide: "eye", text: "Reviews",
  badge: "5", badge_color: "#9333EA" }

// Text with custom font size
{ text: "Push", bg_color: "#F05032", font_size: 24 }

// Emoji
{ emoji: "🚀", text: "Deploy",
  bg_color: "linear-gradient(#16A34A, #15803D)" }

/task skill — the killer feature

Claude Code slash command that aggregates your current task's context and sets up a Stream Deck folder.

Install

mkdir -p ~/.claude/commands
cp node_modules/streamdeck-mcp/commands/task.md ~/.claude/commands/

Or if installed from source:

cp commands/task.md ~/.claude/commands/

Usage

# Search Notion → extract PR/Slack/Figma links automatically
/task PROJ-123

# Read Slack thread → extract all URLs (Notion, GitHub, Figma, Sheets)
/task https://slack.com/archives/...

# Create a plain task folder
/task PR review cleanup

# Auto-detect from current Git branch
/task

# Clear slot 3
/task clear 3

The skill supports up to 7 task folders (Row 1 + Row 2) and row-based issue layout for folders containing multiple related issues.

Requirements

• Node.js 18 or newer
• macOS — the ProfilesV3 path, app icon extraction (sips), and Elgato Stream Deck.app control are all macOS-specific
• Elgato Stream Deck with the desktop app installed

Windows and Linux support is planned but not yet implemented.

Architecture

src/
├── index.ts                  # MCP server entry
├── core/
│   ├── profile-manager.ts    # ProfilesV3 manifest read/write
│   └── icon-renderer.ts      # SVG → PNG pipeline (@resvg/resvg-js)
└── live/                     # Optional background daemon
    ├── standalone.ts
    └── sources/              # Claude Monitor, Git, processes, GitHub PRs

Known limitations

• Folder creation — Stream Deck folders (child profiles) cannot be created purely from manifest files. The Elgato app validates folder references against its internal state. Workaround: create empty folders in the app UI once, then use /task to fill them.
• Live dashboard restart flicker — Applying live updates requires restarting the Stream Deck app, which causes a brief blackout. A native Elgato SDK plugin (Phase 5) would eliminate this.

License

MIT © jxxh204