OpenRGB Status Light MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@OpenRGB Status Light MCP set the case lights to thinking mode"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
OpenRGB 状态灯 MCP

把 AI 的会话状态(思考 / 执行 / 进度 / 完成 / 出错)实时同步到 OpenRGB 控制的机箱灯光(风扇、灯条、灯带均可)。
安装
# 方式一:pipx / uvx(推荐,全局命令)
pipx install git+https://github.com/sheetung/openrgb-mcp.git
uvx --from git+https://github.com/sheetung/openrgb-mcp.git openrgb-mcp
# 方式二:仓库内虚拟环境
git clone https://github.com/sheetung/openrgb-mcp.git
cd openrgb-mcp
python -m venv .venv
.venv/bin/pip install -e . # Windows: .venv\Scripts\pip install -e .启动:
openrgb-mcp # stdio(本地客户端)
openrgb-mcp --transport streamable-http --port 8765 # HTTP接入 DeepSeek Harness:在 %USERPROFILE%\.dsh\profiles\<profile>\cordis.patch.yml 里追加一条
(完整说明见 install/mcp-config.example.yml),保存后热加载、无需重启:
- insert:
- id: magpie-mcp-openrgb
name: "@deepseek-ai/dsh-mcp-client"
config:
serverName: "openrgb"
transport: "stdio"
command: "<openrgb-mcp 可执行文件的绝对路径>"
toolCallTimeoutMs: 20000前置条件:OpenRGB 正在运行且 SDK Server 已启用(端口自动发现:环境变量 OPENRGB_PORT →
OpenRGB 日志记录的端口 → 默认 6742)。
Related MCP server: MCP Govee
MCP 结构
工具(tools)
模型侧工具名为 mcp__openrgb__<tool>。
工具 | 参数 | 执行的动作 |
| — | 读设备清单:设备名、zone 分区、模式、灯珠数量 |
| — | 读当前状态:state、灯珠数、端口、渲染路径、最近错误 |
|
| 切状态 → 按下表改变颜色与效果 |
|
| 进度 → 灯光亮度按比例变化(整体控制),或点亮前 N 颗(逐灯模式) |
|
| 剩余额度 → 亮度按剩余比例,颜色分三档(>50% 绿 / 20–50% 琥珀 / ≤20% 红) |
|
| 整组灯光设为单色 |
|
| 逐灯珠颜色(仅逐灯模式可用) |
|
| 切换到设备硬件效果,停止状态动画 |
| — | 恢复首次接管前的原始灯效 |
状态 → 灯光行为
state | 颜色 | 效果 | 备注 |
|
| 缓慢呼吸 4.0s | 默认空闲态 |
|
| 呼吸 2.4s | 开始推理 |
|
| 呼吸 3.2s | 执行工具 / 改文件 |
|
| 明暗渐变 3.6s | 等你回答 |
|
| 常亮 | 8s 后自动回 |
|
| 明暗渐变 2.8s | 失败 / 异常 |
| 全黑 | — | 关灯 |

所有动画都是连续曲线,没有硬切换,不频闪;颜色、亮度、速度由控制器自己执行,不逐帧重写灯珠。
多个 agent 共用一盏灯
几个 agent(多个会话、多个客户端)同时用同一盏灯时不会互相抢:
每个 agent 把自己的状态登记到一个共享登记表里,灯显示优先级最高的那个:
off>error>waiting>working>thinking>done>idle所有 agent 渲染出的是同一个结果,所以不会出现"两个进程各写各的"导致的闪烁;
status里能看到当前有谁在用(agents)、灯实际显示的是谁(display_state)。超过 90 秒没上报的 agent 视为已退出,退出时也会自动清理登记。
不需要共享时:
config.json里设"share_lamp": false,或用OPENRGB_MCP_REGISTRY指定各自的登记表。
资源(resources)
URI | 内容 |
| 当前灯效状态 JSON |
| 设备 / 分区 / 模式清单 JSON |
提示词(prompt)
status-lamp —— 说明如何把对话状态映射到灯光,供客户端一键载入。
配置(config.json)
键 | 说明 |
|
|
| 亮度上限,默认 |
| 全局亮度系数 |
|
|
| 覆盖各状态的颜色 / 亮度 / 效果 / 周期 |
环境变量:OPENRGB_PORT、OPENRGB_DEVICE、OPENRGB_MCP_CONFIG、OPENRGB_MCP_STATE。
同一时间只让一个程序控制灯光(例如厂商灯控软件),否则会互相覆盖。
许可
本项目以 GPL-3.0 发布(见 LICENSE)。
OpenRGB(GPLv3)——提供 SDK Server 与硬件控制,本项目通过其公开网络协议交互。
openrgb-python(jath03,GPLv3)——开发期间作为 v4 协议线格式的参考实现;本仓库的客户端为独立实现,未复制其源码。
Model Context Protocol Python SDK(MIT)——本项目的 MCP 运行时。
Available Tools
9 toolslist_devicesList OpenRGB devicesARead-only
Read the OpenRGB device inventory: devices, zones, modes and how many LEDs each device has. The LED count is the length of a progress bar.
Inputs: no named parameters. Returns: port, devices, selected, led_count, +1 more
restoreRestore the original lightingADestructiveIdempotent
Restore the colours the device had before this server took over and stop the status animation.
Inputs: no named parameters. Returns: fps, port, quota, ratio, +24 more
set_colorSet a single colour on all LEDsAIdempotent
Paint every LED with one colour (#RRGGBB). brightness (0-1) scales it.
Inputs: color (required), brightness. Returns: fps, port, quota, ratio, +24 more
set_effectRun a hardware effect of the deviceAIdempotent
Hand the LEDs over to one of the device's own effects (for example 'Static', 'Breathing', 'Wave' - the available names depend on the device and are listed by list_devices). This stops the status animation; call set_state again to resume it.
Inputs: effect (required), color. Returns: fps, port, quota, ratio, +24 more
set_ledsSet per-LED coloursAIdempotent
Set an explicit colour per LED (#RRGGBB). The list length must equal the device's LED count - query it with list_devices. Use it for gradients and patterns.
Inputs: colors (required). Returns: fps, port, quota, ratio, +24 more
set_progressShow task progress as an LED barAIdempotent
Turn the LED strip into a progress bar: the completed part is lit, the rest is dark.
Pass percent (0-100) or both done and total. color overrides the bar colour (#RRGGBB). state selects the palette entry (default 'working').
Inputs: done, color, state, total, +2 more. Returns: fps, port, quota, ratio, +24 more
set_quotaShow remaining budget as an LED barBIdempotent
Show how much of a budget is left using the LED count: the bar is filled proportionally to remaining/total and coloured green above 50%, amber between 20% and 50%, red at 20% or less.
Use it for token budgets, API balance, remaining steps and similar.
Inputs: total (required), remaining (required), detail. Returns: fps, port, quota, ratio, +24 more
set_stateSwitch the lamp to a session stateAIdempotent
Switch the host LEDs to a conversation state.
state: idle | thinking | working | waiting | done | error | off (aliases such as complete/failed/ask are accepted). All animations are slow, continuous fades - the lamp never strobes. thinking = blue breathing, working = cyan breathing, waiting = amber fade, done = solid green, error = red fade, idle = dim blue breathing, off = lights out. detail is a short note kept in the status output. animate: set to false to freeze the effect.
Inputs: state (required), detail, animate. Returns: fps, port, quota, ratio, +24 more
statusShow current lamp stateARead-only
Report the current lamp state: state, LED count, device, SDK port, whether the animation is running, active progress/quota and the last error.
Inputs: no named parameters. Returns: fps, port, quota, ratio, +24 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Most tools target clearly different outputs: set_state for semantic lamp states, set_color for a uniform fill, set_leds for per-LED patterns, set_effect for native device effects, and status/list_devices/restore for reads and cleanup. The main overlap is set_progress vs set_quota, which both render a bar and differ only by colour thresholds, and set_state vs set_effect, which both animate the LEDs; the descriptions do clarify the boundary, so confusion is limited rather than pervasive.
Seven of nine tools follow a clean verb_noun pattern (set_state, set_color, set_leds, set_progress, set_quota, set_effect, list_devices). The exceptions are bare 'status' (noun-only) and 'restore' (verb-only), which are readable but break the pattern slightly.
Nine tools is well within the ideal range and each earns its place: two read tools, five distinct LED-control modes, plus a status read and a restore/cleanup path. Nothing feels padded or redundant enough to remove.
The surface covers the full lifecycle of taking over the lamp: inventory, state animation, solid colour, per-LED patterns, progress/quota bars, native effects, status reporting, and restoring the prior colours. Minor gaps remain, such as a global brightness control independent of set_color or a way to persist/query a saved state across sessions.
Related MCP Connectors
Connect any AI to your Foundry VTT world: actors, combat, dice, journals, tokens, compendiums.
One memory, every AI: Claude, ChatGPT, Perplexity, Gemini, Cursor, OpenClaw, Hermes, any MCP client.
Query your Twitch streams, events, supporters, raids & rankings from an AI assistant via OAuth.
AI race engineer for sim racing (Automobilista 2, Assetto Corsa, Assetto Corsa Competizione, Assetto Corsa Evo, RaceRoom). Provides telemetry analysis, braking diagnostics, and leaderboards. Connected via public demo by default. Get your free personal token at [https://flowix.com](https://flowix.com) to analyze your own laps.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to control a local LedFX instance through natural language, allowing management of LED devices, virtuals, effects, scenes, palettes, and playlists.834MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to control Govee smart devices, including lights, via natural language. Supports turning on/off, changing colors, adjusting brightness, and activating scenes through the Govee API or local network.91MIT
- AlicenseAqualityCmaintenanceEnables AI assistants to inspect and safely control OBS Studio over obs-websocket v5, exposing scenes, inputs, filters, outputs and video settings as read and write tools that default to dry runs and refuse changes while live unless explicitly confirmed. It also provides Source Record and IRL readiness checks, a BRB auto-switcher, and a scene timeline log for cutting clips from VODs.17MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI-driven control of Art-Net/sACN DMX lighting, including scenes, effects, groups, safety rules, MIDI/OSC, and Ableton Live integration through a unified command layer.1MIT