{"id":40639842,"url":"https://github.com/verygoodplugins/streamdeck-mcp","last_synced_at":"2026-01-21T08:02:03.980Z","repository":{"id":330380367,"uuid":"1122500199","full_name":"verygoodplugins/streamdeck-mcp","owner":"verygoodplugins","description":"MCP server for Elgato Stream Deck control — set buttons, manage pages, wire actions","archived":false,"fork":false,"pushed_at":"2025-12-25T07:40:14.000Z","size":90,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-26T17:03:59.028Z","etag":null,"topics":["elgato","home-automation","mcp","mcp-server","modelcontextprotocol","streamdeck"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/verygoodplugins.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-24T21:52:03.000Z","updated_at":"2025-12-25T07:40:16.000Z","dependencies_parsed_at":"2025-12-26T17:04:17.929Z","dependency_job_id":null,"html_url":"https://github.com/verygoodplugins/streamdeck-mcp","commit_stats":null,"previous_names":["verygoodplugins/streamdeck-mcp"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/verygoodplugins/streamdeck-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodplugins%2Fstreamdeck-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodplugins%2Fstreamdeck-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodplugins%2Fstreamdeck-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodplugins%2Fstreamdeck-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/verygoodplugins","download_url":"https://codeload.github.com/verygoodplugins/streamdeck-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodplugins%2Fstreamdeck-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28629922,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T04:47:28.174Z","status":"ssl_error","status_checked_at":"2026-01-21T04:47:22.943Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elgato","home-automation","mcp","mcp-server","modelcontextprotocol","streamdeck"],"created_at":"2026-01-21T08:02:01.942Z","updated_at":"2026-01-21T08:02:03.975Z","avatar_url":"https://github.com/verygoodplugins.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎛️ Stream Deck MCP · v0.1.0\n\n\u003c!-- mcp-name: io.github.verygoodplugins/streamdeck-mcp --\u003e\n\n\u003e **Let AI design your Stream Deck setup** — Describe what you want in plain English. Your AI builds it.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n## The Problem\n\nStream Deck is powerful, but configuring it is tedious. Clicking through the GUI, finding icons, setting up multi-page workflows — it takes forever.\n\n## The Solution\n\nTell your AI what you want:\n\n```\n\"Design a podcast studio layout with pages for recording, editing, and publishing.\nInclude buttons for mic mute, recording start/stop, sound effects, and scene switching.\"\n```\n\nYour AI designs the strategy, creates the pages, and configures every button. Done.\n\n## ✨ What You Can Do\n\n🎙️ **\"Set up my Stream Deck for podcasting\"** — AI designs a multi-page system\n🏠 **\"Create a home automation page\"** — Buttons for lights, scenes, climate\n🎮 **\"Build a gaming profile with Discord, OBS, and Spotify\"** — One prompt, full setup\n🔄 **\"Redesign my layout to be more intuitive\"** — AI understands workflow, suggests improvements\n\nWorks with: Stream Deck, Stream Deck Mini, Stream Deck XL, Stream Deck MK.2, Stream Deck +\n\n## ⚠️ Important: Quit Elgato Software First\n\n**This MCP server requires exclusive USB access.** You must quit the Elgato Stream Deck software before using it:\n\n```bash\n# macOS — quit Elgato software\nkillall \"Stream Deck\" 2\u003e/dev/null || true\n```\n\nThe Stream Deck can only be controlled by one application at a time. While using this MCP server, the Elgato software cannot run (and vice versa).\n\n---\n\n## 🏃 Quick Start — 2 Minutes to Buttons\n\n### 1️⃣ Prerequisites\n\n```bash\n# macOS\nbrew install hidapi\n\n# Linux (Debian/Ubuntu)\nsudo apt install libhidapi-libusb0\n\n# Linux udev rule (required for non-root access)\nsudo tee /etc/udev/rules.d/10-streamdeck.rules \u003c\u003c EOF\nSUBSYSTEMS==\"usb\", ATTRS{idVendor}==\"0fd9\", GROUP=\"users\", MODE=\"0666\"\nEOF\nsudo udevadm control --reload-rules\n```\n\n### 2️⃣ Install\n\n```bash\ngit clone https://github.com/verygoodplugins/streamdeck-mcp.git\ncd streamdeck-mcp\nuv venv \u0026\u0026 uv pip install -e .\n```\n\n### 3️⃣ Add to Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"streamdeck\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"/path/to/streamdeck-mcp\",\n        \"run\",\n        \"server.py\"\n      ]\n    }\n  }\n}\n```\n\n### 4️⃣ Use It\n\nIn Claude:\n```\nConnect to my Stream Deck\n```\n\nThen:\n```\nSet button 0 to \"Lights\" with a blue background\nSet button 1 to \"Music\" with action \"open -a Spotify\"\nCreate a page called \"gaming\" and switch to it\n```\n\nThat's it! 🎉\n\n## 🛠️ Available Tools\n\n| Tool | What it does |\n|------|-------------|\n| `streamdeck_connect` | Connect to first available deck |\n| `streamdeck_info` | Get deck model, key count, current page |\n| `streamdeck_set_button` | Set text, image, colors, and action |\n| `streamdeck_clear_button` | Clear a single button |\n| `streamdeck_set_brightness` | 0-100% brightness |\n| `streamdeck_create_page` | Create a new button profile |\n| `streamdeck_switch_page` | Switch active page |\n| `streamdeck_list_pages` | List all pages |\n| `streamdeck_delete_page` | Delete a page (except \"main\") |\n| `streamdeck_disconnect` | Clean disconnect |\n\n### Natural Language Examples\n\nJust tell Claude what you want:\n\n- \"Connect to my Stream Deck and show me the layout\"\n- \"Set button 0 to say 'Lights' with a blue background\"\n- \"Make button 4 open Spotify when I press it\"\n- \"Create a 'gaming' page with Discord, Steam, and OBS buttons\"\n- \"Switch to the gaming page\"\n- \"Set brightness to 50%\"\n\n## 📐 Button Layout\n\nButtons are numbered left-to-right, top-to-bottom:\n\n**Stream Deck (15 keys, 5×3):**\n```\n[0]  [1]  [2]  [3]  [4]\n[5]  [6]  [7]  [8]  [9]\n[10] [11] [12] [13] [14]\n```\n\n**Stream Deck Mini (6 keys, 3×2):**\n```\n[0]  [1]  [2]\n[3]  [4]  [5]\n```\n\n**Stream Deck XL (32 keys, 8×4):**\n```\n[0]  [1]  [2]  [3]  [4]  [5]  [6]  [7]\n[8]  [9]  [10] [11] [12] [13] [14] [15]\n[16] [17] [18] [19] [20] [21] [22] [23]\n[24] [25] [26] [27] [28] [29] [30] [31]\n```\n\n## 🏠 Home Assistant Integration\n\nWire buttons to your HA entities. Example prompt:\n\n```\nSet up my Stream Deck for home control:\n- Button 0: \"Office Lights\" that toggles light.office_ceiling\n- Button 1: \"All Off\" that runs a scene\n- Button 4: Page switch to \"media\" page\n```\n\nThe action field accepts any shell command — use `curl` to hit HA webhooks or the HA CLI.\n\n## 🎨 Custom Icons\n\nDrop PNG/JPG files anywhere and reference them:\n\n```\nSet button 5 with image ~/icons/spotify.png\n```\n\nImages auto-scale to button size (72×72 or 96×96 depending on deck model).\n\n## 📁 State Storage\n\nConfigs persist at `~/.streamdeck-mcp/`:\n- `pages.json` — Button appearances per page\n- `buttons.json` — Button actions per page\n\n## ⚠️ Troubleshooting\n\n**\"No Stream Deck found\"**\n- Check USB connection\n- On Linux: Did you add the udev rule and reload?\n- On macOS: Grant terminal USB access in System Preferences → Security \u0026 Privacy\n\n**\"streamdeck library not installed\"**\n```bash\nuv pip install streamdeck pillow\n```\n\n**Buttons don't respond to presses**\n- Physical button callbacks require the MCP server to stay running\n- The server runs while Claude Desktop is open\n\n**\"Deck disconnected\" errors**\n- The server handles USB disconnections gracefully\n- Just say \"Connect to my Stream Deck\" again to reconnect\n\n## 🧪 Development\n\n```bash\n# Setup\nuv venv \u0026\u0026 uv pip install -e \".[dev]\"\n\n# Run server\nuv run server.py\n\n# Run tests (no hardware required)\nuv run pytest tests/ -v\n\n# Lint\nuv run ruff check .\n```\n\n## 🔮 Roadmap\n\n- [ ] Home Assistant entity browser integration\n- [ ] Icon generation from emoji\n- [ ] Button press webhooks\n- [ ] Multi-deck support\n\n## License\n\nMIT — Because hardware control should be free.\n\n---\n\n*Built by [Jack Arturo](https://verygoodplugins.com/?utm_source=github) at Very Good Plugins* 🧡\n\n[![X (Twitter)](https://img.shields.io/badge/follow-@jjack__arturo-black?logo=x)](https://x.com/jjack_arturo)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverygoodplugins%2Fstreamdeck-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fverygoodplugins%2Fstreamdeck-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverygoodplugins%2Fstreamdeck-mcp/lists"}