mcp-divoom-lan

mcp-divoom-lan is an open-source MCP server that wraps Divoom watchface LAN APIs as standard tools for AI clients.

It works together with the v2 HTML visual editor for modifying watchfaces, switching faces, adjusting brightness, and creating new local watchfaces.

v2 visual editor (public):

• GitHub: https://github.com/DivoomDevelop/divoom-watchface-visual-editor_v2
• Live site: https://divoomdevelop.github.io/divoom-watchface-visual-editor_v2/

Your local clone path (e.g. D:\divoom-watchface-visual-editor) is machine-specific; use the v2 GitHub / GitHub Pages URLs above in docs and MCP metadata.

Goals

• Expose key capabilities from Divoom_Watchface_Remote_Customization_Guide_EN.md as MCP tools
• Let MCP-enabled clients (Cursor, Claude Desktop, local LLMs, etc.) drive watchface actions via natural language
• Preserve safety boundaries (read before write, explicit warnings for risky operations, multipart rules)

Default safety policy (important)

• Read before write: call watchface_get_local, then watchface_patch_local, then read back to verify.
• If GetLocalClockInfo returns an empty ItemList: stop writes; switch to an editable watchface first.
• Do not call watchface_create_local_clock unless the user clearly asks to create a new one (no implicit creation).

Implemented tools

• watchface_get_local → Device/GetLocalClockInfo
• watchface_patch_local → Device/PatchLocalClockInfo (default /divoom_api); optional dialAssetsPath switches to multipart POST /patch_local_clock (same dial/tar.gz rules as watchface_create_local_clock)
• watchface_get_fonts_local → Device/GetLocalFontList
• watchface_get_store_market_list → Device/GetStoreClockMarketList
• watchface_set_clock_select → Channel/SetClockSelectId
• watchface_get_brightness → Sys/GetBrightness
• watchface_set_brightness → Channel/SetBrightness
• watchface_onoff_screen → Channel/OnOffScreen (1=on, 0=off)
• watchface_replace_dial_bg_file → POST /replace_clock_dial_bg
• watchface_upload_file → POST /upload
• watchface_create_local_clock → POST /create_local_clock (multipart: single dial image or tar.gz; JSON DialAssets/UseDialAssetBundle selects mode, default auto-detect gzip)
• watchface_reset_local_then_cloud → Device/ResetLocalClockFromServer
• watchface_get_screen_snapshot → Device/GetScreenSnapshot (wait 2s, then GET /userdata/snapshot.webp for visual diff)
• watchface_raw_command → generic POST /divoom_api
• watchface_protocol_quick_reference → key protocol constraints for the model

Resources (context for the model)

The server exposes two MCP resources:

• divoom://guide/quick-reference
• divoom://skill/watchface-customization

MCP Bundle (.mcpb)

For MCPB-compatible hosts (e.g. Claude desktop connectors, Smithery stdio releases), build a local bundle:

1. Install the packer: npm install -g @anthropic-ai/mcpb
2. From this package root: npm run mcpb:pack
3. Output: mcp-divoom-lan.mcpb (gitignored). The staging directory mcpb/staging/ is also gitignored.

The bundle includes dist/, resources/, production node_modules, and a manifest.json with user fields for device IP, port, and timeout.

Quick start

cd tools/mcp-divoom-lan  # or your clone root for this package
npm install
npm run build
npm start

Development (watch rebuild):

npm run dev

Pre-release check (typecheck, build, pack dry-run):

npm run release:check

Documentation

• docs/README.md — documentation index
• docs/quick-start.md — minimal setup
• docs/tool-examples.md — tool usage examples (includes §5b analog pointer layout)
• docs/disp-usage.md — choosing disp ids (pointer layout 131/132/233; net-gallery uniqueness 13/125–130/173–175)
• docs/html-visual-editor.md — using the visual editor with MCP
• `docs/safety-and-troubleshoo

... View full README on GitHub