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

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.