divoom-agent-mcp 0.1.0

MCP server exposing the divoom-agent semantic API as tools for LLMs (Claude, etc.)

divoom-agent-mcp

MCP server that exposes the divoom-agent semantic API as tools for LLMs. Lets Claude (or any MCP-aware tool-using model) drive a Divoom 16x16 LED panel as an ambient AI peripheral.

Top of the three-library stack:

divoom-protocol     ← bytes/BLE/encoder
divoom-agent        ← semantic ambient API
divoom-agent-mcp    ← THIS PACKAGE. MCP tools for LLM use.

Install

pip install -e .[dev]

This installs the divoom-agent-mcp console script.

Usage with Claude Code

Add to your Claude Code MCP config (~/.claude/mcp.json or via claude mcp add):

{
  "mcpServers": {
    "divoom-agent": {
      "command": "divoom-agent-mcp",
      "env": {
        "DIVOOM_ADDRESS": ""
      }
    }
  }
}

Leave DIVOOM_ADDRESS empty to auto-scan for the nearest Divoom on startup, or set it to a specific device address (BLE MAC on Linux/Pi, or a CoreBluetooth UUID on macOS) to pin to a specific panel.

The server connects lazily on first tool invocation, so adding the MCP config doesn't immediately wake the panel.

Tools exposed

Tool	What it does
set_status(state)	Ambient state: thinking / working / idle / success / error. Loops until replaced.
notify(kind)	Discrete event: shipped / celebrate / message.
set_alert(level)	Severity ladder 1-3: yellow / orange / red flash.
paint_pixels(grid)	Custom 16x16 pixel art. Grid is a list of 16 rows × 16 cells × [R,G,B].
set_color(r, g, b, brightness)	Solid Lighting color.
set_brightness(value)	0-100.
clear_panel()	Black.
show_clock()	Built-in clock channel.
start_mondrian(fps)	Generative Mondrian cycle.
stop_animation()	Cancel any running animation.

Example LLM-driven sessions

Once configured, Claude can compose moves like:

"Show that you're thinking about my question." → set_status("thinking") → blue breath on the panel

"I just shipped a deploy — celebrate for a few seconds, then go back to idle." → notify("celebrate") → wait → set_status("idle")

"Paint me a sunset on the panel." → paint_pixels([... orange/red gradient ...])

Development

.venv/bin/pip install -e .[dev]
.venv/bin/pytest                    # currently no live-BLE tests
.venv/bin/divoom-agent-mcp          # run server interactively (uses stdio)

Test from another terminal with an MCP client (e.g. the official mcp CLI inspector) or just point Claude Code at it.

License

MIT.