Skip to main content
Glama
OpenRGB Status Light MCP

OpenRGB Status Light MCP

by sheetung

OpenRGB 状态灯 MCP

OpenRGB 状态灯

把 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>。

工具

参数

执行的动作

list_devices

—

读设备清单:设备名、zone 分区、模式、灯珠数量

status

—

读当前状态:state、灯珠数、端口、渲染路径、最近错误

set_state

state:idle thinking working waiting done error off;detail 说明(仅记录);animate 是否动画

切状态 → 按下表改变颜色与效果

set_progress

percent 0–100,或 done+total;color、state、detail

进度 → 灯光亮度按比例变化(整体控制),或点亮前 N 颗(逐灯模式)

set_quota

remaining、total;detail

剩余额度 → 亮度按剩余比例,颜色分三档(>50% 绿 / 20–50% 琥珀 / ≤20% 红)

set_color

color #RRGGBB;brightness 0–1

整组灯光设为单色

set_leds

colors:#RRGGBB 数组,长度 = 灯珠数

逐灯珠颜色(仅逐灯模式可用)

set_effect

effect:设备自带模式名(如 Breathing、Static、Wave);color

切换到设备硬件效果,停止状态动画

restore

—

恢复首次接管前的原始灯效

状态 → 灯光行为

state

颜色

效果

备注

idle

#2a3a5a 暗蓝

缓慢呼吸 4.0s

默认空闲态

thinking

#3a86ff 蓝

呼吸 2.4s

开始推理

working

#00d4ff 青

呼吸 3.2s

执行工具 / 改文件

waiting

#ffb703 琥珀

明暗渐变 3.6s

等你回答

done

#2ecc71 绿

常亮

8s 后自动回 idle

error

#ff4d4f 红

明暗渐变 2.8s

失败 / 异常

off

全黑

—

关灯

状态与亮度映射

所有动画都是连续曲线,没有硬切换,不频闪;颜色、亮度、速度由控制器自己执行,不逐帧重写灯珠。

多个 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

内容

openrgb://status

当前灯效状态 JSON

openrgb://devices

设备 / 分区 / 模式清单 JSON

提示词(prompt)

status-lamp —— 说明如何把对话状态映射到灯光,供客户端一键载入。

配置(config.json)

键

说明

control

global(默认,整组灯光一个颜色 + 亮度)或 per_led(逐灯珠,仅可寻址设备)

max_brightness

亮度上限,默认 0.7(约 178/255)

brightness

全局亮度系数

done_hold_seconds

done 保持多久后回 idle,默认 8 秒

palette

覆盖各状态的颜色 / 亮度 / 效果 / 周期

环境变量: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 tools
list_devicesList OpenRGB devicesA
Read-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 lightingA
DestructiveIdempotent

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 LEDsA
Idempotent

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 deviceA
Idempotent

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 coloursA
Idempotent

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 barA
Idempotent

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 barB
Idempotent

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 stateA
Idempotent

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 stateA
Read-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

    A3.8/5.0

    Scored across 9 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      9
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      17
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      1
      MIT