Skip to main content
Glama
Sign In
mcp-divoom-lan

mcp-divoom-lan

Official
by DivoomDevelop
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

mcp-divoom-lan

mcp-divoom-lan is an open-source MCP server for TimesFrame/AstroToo watchfaces and PIXOO64/TimeGate LAN display control. TimesFrame/AstroToo query Device/GetHardwareVersion; PIXOO64/TimeGate use discovery Hardware or explicit hardware profiles. Unknown hardware is rejected. The TimesFrame no-response fallback is retained after checking available discovery data.

PIXOO64 Hardware 90/92 uses 80/post; 96 uses 9000/divoom_api. Its 10 dedicated tools send display elements, text, RGB animations and control commands. Hardware 96 command lists execute sequentially in MCP to match the reference firmware. See the PIXOO64 guide and examples. Device firmware is unchanged.

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

TimeGate Hardware 400 uses 80/post; 402 uses 9000/divoom_api. Its 10 dedicated tools control five independent 128×128 screens and require LocalToken from device settings. Hardware 402 batches run sequentially in MCP. See the TimeGate guide for per-version field, alignment and background differences. Device firmware is unchanged.

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)

Related MCP server: @qirabot/mcp

Default safety policy (important)

  • Select the product profile: Hardware 510/511/512 selects TimesFrame; 530 AstroToo; 90/92/96 PIXOO64; 400/402 TimeGate. Explicit target.hardware is a caller profile override. Use pixoo64_* or timegate_* for those products; managed-watchface rules below apply to TimesFrame/AstroToo.

  • Internal managed slot: users and MCP clients omit ClockId from create and patch calls. The server injects its managed slot, reads it first, creates it when missing, and updates it when present.

  • Read before write: the MCP server prechecks its managed slot, writes, and then clients should read back to verify.

  • If GetLocalClockInfo returns an empty ItemList: stop writes; switch to an editable watchface first.

  • Prefer watchface_patch_local for edits. Use watchface_create_local_clock when the user asks to create a watchface or when intentionally replacing the complete managed configuration and backdrop.

Implemented tools (42)

Discovery tool (1):

  • watchface_list_devices → returns selectable TimesFrame/AstroToo/PIXOO64/TimeGate targets with product-specific default ports

Device tools (15):

  • watchface_get_device_info → hardware identification and LAN capability report

  • watchface_get_local → Device/GetLocalClockInfo

  • watchface_patch_local → managed-slot upsert with no caller-supplied ClockId. Existing configurations use Device/PatchLocalClockInfo; a missing configuration is created when a backdrop and complete item tables are supplied.

  • watchface_get_fonts_local → Device/GetLocalFontList

  • watchface_get_store_market_list → Device/GetStoreClockMarketList

  • watchface_set_clock_select → Channel/SetClockSelectId (TimesFrame queues a paired request inside one serialized MCP operation so a manual selection suppresses the active traditional schedule for the current period; AstroToo sends once)

  • 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 → AstroToo-only POST /upload_local_asset; returns a temporary local:// staging reference consumed by a successful create/patch. AstroToo keeps product photo/pixel POST /upload separate. TimesFrame generic /upload is blocked in local-only MCP mode.

  • watchface_create_local_clock → managed-slot multipart upsert with no caller-supplied ClockId: /create_local_clock when missing and /patch_local_clock when already present.

  • watchface_reset_local_then_cloud → Device/ResetLocalClockFromServer

  • watchface_get_screen_snapshot → Device/GetScreenSnapshot (downloads the returned AstroToo snapshot path; TimesFrame keeps its WebP fallback)

  • watchface_raw_command → generic POST /divoom_api

Offline/model-aware authoring tools (6):

  • watchface_protocol_quick_reference → key protocol constraints for the model

  • watchface_clock_catalog → product-specific ClockId, Chinese/English names, fonts, disp and item-id semantics; optional native configuration

  • watchface_disp_catalog → model-specific disp catalog and filters

  • watchface_font_catalog → model-specific font catalog; with a live AstroToo target it merges local availability into the AstroToo names

  • watchface_template_search → curated TimesFrame or AstroToo watchface templates

  • watchface_layout_suggest → model-specific layout hints; AstroToo never receives TimesFrame coordinate statistics

PIXOO64 tools (10): pixoo64_get_device_info, pixoo64_send_animation, pixoo64_send_items, pixoo64_send_text, pixoo64_clear_text, pixoo64_set_brightness, pixoo64_onoff_screen, pixoo64_set_channel, pixoo64_play_gif, and pixoo64_command_list. Read divoom://pixoo64/guide and divoom://pixoo64/example. A direct LAN target can be { "host":"192.168.1.100", "model":"pixoo64", "hardware":90 }; omit port and DIVOOM_DEVICE_PORT to select the version's default.

TimeGate tools (10): timegate_get_device_info, timegate_send_items, timegate_send_text, timegate_clear_text, timegate_set_brightness, timegate_get_brightness, timegate_onoff_screen, timegate_select_clock, timegate_play_gif, and timegate_command_list. Read divoom://timegate/guide and divoom://timegate/example; authenticated calls supply localToken from the actual device settings.

Resources (context for the model)

Product data is stored by directory: resources/timesframe, resources/astrotoo, resources/pixoo64, resources/timegate, and resources/common. resources/products.json records Hardware mappings, per-screen canvas sizes, directories and routes. Runtime loaders never fall back to another product's data.

The original resource URIs retain TimesFrame semantics. AstroToo has separate 480×480 resources:

  • divoom://products/catalog

  • divoom://guide/quick-reference

  • divoom://skill/watchface-customization

  • divoom://font/catalog

  • divoom://font/guide

  • divoom://disp/catalog

  • divoom://watchface/schema

  • divoom://watchface/example-minimal

  • divoom://guide/ai-watchface

  • divoom://templates/curated

  • divoom://astrotoo/guide

  • divoom://astrotoo/disp/summary

  • divoom://astrotoo/disp/catalog

  • divoom://astrotoo/disp/guide/en

  • divoom://astrotoo/disp/guide/zh-cn

  • divoom://astrotoo/font/catalog

  • divoom://astrotoo/clocks/catalog

  • divoom://astrotoo/clocks/configs

  • divoom://astrotoo/templates/curated

  • divoom://astrotoo/watchface/example-minimal

  • divoom://astrotoo/watchface/schema

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, product detection, and timeout.

Quick start

Published npm package:

{
  "mcpServers": {
    "divoom-lan": {
      "command": "npx",
      "args": ["-y", "mcp-divoom-lan@latest"],
      "env": {
        "DIVOOM_DEVICE_HOST": "192.168.1.120",
        "DIVOOM_DEVICE_PORT": "9000",
        "DIVOOM_DEVICE_MODEL": "auto",
        "DIVOOM_TIMEOUT_MS": "45000"
      }
    }
  }
}

DIVOOM_DEVICE_HOST is optional. Leave it unset and include target.host in each tool call when one MCP server controls multiple devices.

Build from source:

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

Regenerate AstroToo resources from the simulator and Divoom command server:

$env:DIVOOM_ASTROTOO_SIMULATOR_ROOT='D:\work\divoom_product\timebox\trunck\device\tool_src\lv_sim_visual_studio\LvglAstroTooSimulator'
$env:DIVOOM_ASTROTOO_DEVICE_ID='300400436'
npm run build:astrotoo

The generator calls https://appchina.divoom-gz.com/ + command string with a JSON body. It obtains default IDs from Device/GetClockDefaultList (IsDefault=1), font names from Device/GetFontForAI, and missing configurations from Device/GetClockInfoV3.

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/mcp-tools.md — complete 42-tool API catalog and model-specific file policy

  • docs/astrotoo-and-multiple-devices.md — hardware detection, multiple targets, and AstroToo local storage

  • docs/astrotoo-watchface-workflow.md — release-ready AstroToo create, update, switch, and screenshot workflow

  • docs/adding-products.md — product registry, isolated resource directories, and onboarding checks

  • 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-troubleshooting.md — safety and FAQs

  • docs/reference/ — condensed protocol rules (EN/ZH)

  • docs/examples/ — sample requests/responses and catalog

Environment variables

  • DIVOOM_DEVICE_HOST — device LAN IP (e.g. 192.168.1.120)

  • DIVOOM_DEVICE_PORT — optional override; omit for PIXOO64 90/92 or TimeGate 400 port 80, otherwise 9000

  • DIVOOM_DEVICE_MODEL — auto (default), timesframe, astrotoo, pixoo64, or timegate

  • DIVOOM_DEVICE_HARDWARE — optional default-device profile: PIXOO64 90/92/96 or TimeGate 400/402; omit to use discovery

  • DIVOOM_TIMEGATE_LOCAL_TOKEN — optional LocalToken from the default TimeGate settings; matched by host, otherwise supply localToken per call

  • DIVOOM_TIMEOUT_MS — request timeout ms, default 45000

If DIVOOM_DEVICE_HOST is unset, each tool call must pass target.host. To control several devices, pass a different target on each call. The server serializes a complete operation per host while allowing independent devices to run concurrently.

Example client config (stdio)

Cursor / Claude Desktop

{
  "mcpServers": {
    "divoom-lan": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/to/tools/mcp-divoom-lan/dist/index.js"
      ],
      "env": {
        "DIVOOM_DEVICE_HOST": "192.168.1.120",
        "DIVOOM_DEVICE_PORT": "9000",
        "DIVOOM_DEVICE_MODEL": "auto",
        "DIVOOM_TIMEOUT_MS": "45000"
      }
    }
  }
}

You can also copy client-config.example.json in this directory as a starting point.

Publishing checklist (for maintainers)

  1. Use a dedicated repo (e.g. mcp-divoom-lan) with this package at the repo root.

  2. Verify metadata: LICENSE, SECURITY.md, CONTRIBUTING.md, CHANGELOG.md, RELEASE.md as applicable.

  3. Run npm run release:check.

  4. Tag a GitHub release (e.g. v0.3.0) with screenshots and sample requests if helpful.

  5. Submit listings where appropriate (MCP Registry, Smithery, Glama, MCP.so, and community indexes). For Glama, follow GLAMA_SUBMISSION_READY.md (including Dockerfile and glama.json). For MCP.so, follow MCP_SO_SUBMISSION_READY.md. For the Volcengine MCP catalog, see VOLCENGINE_SUBMISSION_READY.md (PR: https://github.com/volcengine/mcp-server/pull/398). For an Alibaba Cloud Bailian custom MCP deployed with npx, see BAILIAN_MCP_SUBMISSION_READY.md. For publishing a Coze HTTP plugin, see COZE_SUBMISSION_READY.md.

  6. Minimal demo flow: watchface_get_local → watchface_patch_local (font size/color) → watchface_replace_dial_bg_file (background).

Files often used at release

Included in this repo (when present): LICENSE, CHANGELOG.md, CONTRIBUTING.md, SECURITY.md, RELEASE.md, optional checklist and directory templates, and .github/workflows/ci.yml.

Should the HTML visual editor ship inside this npm package?

Recommendation: no for the core MCP package — keep MCP lean. Offer the editor as a separate optional project.

  • Core: https://github.com/DivoomDevelop/mcp-divoom-lan

  • Visual editor v2: https://github.com/DivoomDevelop/divoom-watchface-visual-editor_v2

  • Hosted v2: https://divoomdevelop.github.io/divoom-watchface-visual-editor_v2/

Benefits:

  • Small MCP install suitable for all AI clients

  • Non-developers can use the visual UI to understand ItemList, then let the AI apply patches

  • Clear split between WYSIWYG editing and automated MCP writes

Alignment with upstream docs

This repo ships standalone docs under docs/, docs/reference/, and docs/examples/. If you maintain full guides elsewhere, keep this tree synced or treat it as the distribution subset.

Available Tools

42 tools
pixoo64_clear_textA

Clear all HTTP text and display-list overlays using Draw/ClearHttpText. PIXOO64 Hardware 90/92/96 only. Provide target.hardware for direct LAN use, or resolve it using device discovery.

Inputs: target.

pixoo64_command_listA

Validate all commands before sending. Hardware 90/92 uses native Draw/CommandList (firmware 90102+); Hardware 96 sends the supported commands sequentially because the reference firmware has no native list handler. Stops on first failure; earlier commands may already have run. Nested lists and unsupported commands are rejected. PIXOO64 Hardware 90/92/96 only. Provide target.hardware for direct LAN use, or resolve it using device discovery.

Inputs: commands (required), target.

pixoo64_get_device_infoB

Report the 64×64 profile, version-specific route and declared MCP support. Explicit Hardware is a caller override, not a device query. PIXOO64 Hardware 90/92/96 only. Provide target.hardware for direct LAN use, or resolve it using device discovery.

Inputs: target.

pixoo64_onoff_screenA

Set Channel/OnOffScreen, 1=on, 0=off. PIXOO64 Hardware 90/92/96 only. Provide target.hardware for direct LAN use, or resolve it using device discovery.

Inputs: onOff (required), target.

pixoo64_play_gifA

Play a device-accessible HTTP GIF URL using Device/PlayTFGif (16×16, 32×32 or 64×64). The device downloads the URL. Legacy firmware requires 90096+. PIXOO64 Hardware 90/92/96 only. Provide target.hardware for direct LAN use, or resolve it using device discovery.

Inputs: url (required), target.

pixoo64_send_animationA

Send 1–59 RGB888 frames in order; reset the HTTP GIF ID then use PicID=1. Frames are row-major RGB base64, not PNG/JPEG/GIF bytes. Stops on first failure; never retries a partially sent animation. PIXOO64 Hardware 90/92/96 only. Provide target.hardware for direct LAN use, or resolve it using device discovery.

Inputs: frames (required), speed, width, target.

pixoo64_send_itemsA

Send time/date/weather/text elements using Draw/SendHttpItemList. Requires a previously sent animation; backgroundColor optionally starts a solid 64×64 background first. IDs 0–39 replace matching overlays. Read divoom://pixoo64/guide for types 1–23 and font policy. PIXOO64 Hardware 90/92/96 only. Provide target.hardware for direct LAN use, or resolve it using device discovery.

Inputs: items (required), target, backgroundColor.

pixoo64_send_textA

Add or replace a text overlay using Draw/SendHttpText. Requires a previously sent animation; backgroundColor optionally starts a solid 64×64 background first. Text fonts are 0–7. Legacy firmware requires 90102+. PIXOO64 Hardware 90/92/96 only. Provide target.hardware for direct LAN use, or resolve it using device discovery.

Inputs: text (required), target, backgroundColor.

pixoo64_set_brightnessB

Set Channel/SetBrightness, 0–100. PIXOO64 Hardware 90/92/96 only. Provide target.hardware for direct LAN use, or resolve it using device discovery.

Inputs: brightness (required), target.

pixoo64_set_channelA

Set Channel/SetIndex, 0=faces, 1=cloud, 2=visualizer, 3=custom, 4=black screen. PIXOO64 Hardware 90/92/96 only. Provide target.hardware for direct LAN use, or resolve it using device discovery.

Inputs: index (required), target.

timegate_clear_textB

Clear animation text using Draw/ClearHttpText and LcdId. textId=-1 clears all text on the selected animation. This does not delete display-list custom dials. TimeGate Hardware 400/402 only; five independent 128×128 screens. Read divoom://timegate/guide.

Inputs: textId (required), lcdIndex (required), target, localToken.

timegate_command_listA

Validate the complete whitelist batch before writing. 400 uses native Draw/CommandList; 402 executes commands sequentially in MCP because the reference firmware has no list handler. No nested lists, token overrides or unsupported commands. Stops on failure without retry or rollback; earlier commands may have run. TimeGate Hardware 400/402 only; five independent 128×128 screens. Read divoom://timegate/guide.

Inputs: commands (required), target, localToken.

timegate_get_brightnessA

Read brightness: 400 uses Channel/GetAllConf; 402 reads effective brightness through Channel/GetClockInfo on LCD 0. The reference 402 Sys/GetBrightness returns a hardcoded 100 and is not used. Effective brightness is 0 when the screen is off. TimeGate Hardware 400/402 only; five independent 128×128 screens. Read divoom://timegate/guide.

Inputs: target, localToken.

timegate_get_device_infoB

Report the selected hardware profile, endpoint and per-screen canvas; explicit hardware is a caller override, not a queried device identity. TimeGate Hardware 400/402 only; five independent 128×128 screens. Read divoom://timegate/guide.

Inputs: target.

timegate_onoff_screenA

Switch all screens, onOff=1 on and 0 off. TimeGate Hardware 400/402 only; five independent 128×128 screens. Read divoom://timegate/guide.

Inputs: onOff (required), target, localToken.

timegate_play_gifA

Play 1–9 HTTP GIF URLs on the selected screens using Device/PlayGif. GIF dimensions must be square 16/32/64/128. URLs are downloaded by the device; an acknowledgement does not verify rendering. TimeGate Hardware 400/402 only; five independent 128×128 screens. Read divoom://timegate/guide.

Inputs: urls (required), lcdArray (required), target, localToken.

timegate_select_clockA

Select a whole-device clock when lcdIndex is omitted. For one screen, provide lcdIndex and lcdIndependence from the device's existing configuration; no default independence ID is assumed. TimeGate Hardware 400/402 only; five independent 128×128 screens. Read divoom://timegate/guide.

Inputs: clockId (required), target, lcdIndex, localToken, +1 more.

timegate_send_itemsA

Create or update one screen with Draw/SendHttpItemList. mode=replace sends NewFlag=1; append sends 0. On first use of a 402 screen, supply backgroundGif with replace to initialize its background; missing background data can prevent visible rendering despite a success acknowledgement. 400 documentation says background is ignored on replace. MCP does not download the background itself. TimeGate Hardware 400/402 only; five independent 128×128 screens. Read divoom://timegate/guide.

Inputs: items (required), lcdIndex (required), mode, target, +2 more.

timegate_send_textA

Add text to an already active HTTP animation. lcdIndex must be the animation's first selected screen. 400 sends LcdIndex; 402 source reads LcdId. Text uses animation fonts 0–7 and a 16-pixel height, independently of display-list fonts. For regular custom dials use send_items type 22. TimeGate Hardware 400/402 only; five independent 128×128 screens. Read divoom://timegate/guide.

Inputs: text (required), lcdIndex (required), target, localToken.

timegate_set_brightnessA

Set global LCD brightness, 0–100. TimeGate Hardware 400/402 only; five independent 128×128 screens. Read divoom://timegate/guide.

Inputs: brightness (required), target, localToken.

watchface_clock_catalogA

Query product-specific ClockId, Chinese/English names, font ids, disp ids, item ids, and optional source configuration. AstroToo data is generated from both simulator clocksys directories; its default set comes from Device/GetClockDefaultList with IsDefault=1. TimesFrame data remains independent. For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Inputs: disps, fonts, limit, model, +7 more.

watchface_create_local_clockA

Upsert the MCP-managed local watchface with multipart. The server injects its managed ClockId, reads that slot first, creates it only when missing, and otherwise updates it. Callers do not provide a ClockId. TimesFrame accepts DialAssets image/auto/bundle and may use clock_bg.tar.gz. AstroToo accepts DialAssets=image only: upload every element separately with watchface_upload_file, put each returned local:// FileId in ItemList[i].image_addr, then call this tool with one 480x480 JPEG/WebP backdrop. AstroToo rejects TAR/TGZ/ZIP, UseDialAssetBundle!=0, and bundle_image. For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Inputs: metadata (required), imagePath (required), target, fileName, +1 more.

watchface_disp_catalogA

Return the selected product's disp catalog for ItemList[i].disp and ItemPatchList[i].patch.disp. TimesFrame and AstroToo use independent enums and renderer sources. AstroToo entries also report category, render kind, data source, asset requirement, authoring mode, and reference-config usage. For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Inputs: ids, limit, model, target, +8 more.

watchface_font_catalogA

Return a curated font catalog so agents can pick ItemList[i].font ids deterministically. Each entry includes id, type (1=TTF, 0=image-font), display name, original charset, derived script (digits / digits-extended / latin / cjk), style tags (sans/serif/pixel/digital/handwriting/display/decorative/bold/light/etc), and recommendedFor (scenario names like time_digits / temperature_digits / weather_text / user_text / lunar_text). The response also includes a scenarios map that lists which disp ids each scenario covers and which tags to prefer. For visual style and mood per font id, read MCP resource divoom://font/guide first. Use the optional filters to narrow the result. Always cross-check with watchface_get_fonts_local before committing a font id to a real device, because the on-device font list may be a subset. For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Inputs: ids, tag, type, limit, +6 more.

watchface_get_brightnessC

Call Sys/GetBrightness. For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Inputs: target.

watchface_get_device_infoB

Return the product profile and LAN capabilities. TimesFrame/AstroToo query Hardware; PIXOO64/TimeGate use discovery or an explicit target.hardware profile. Unknown Hardware is rejected. For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Inputs: target.

watchface_get_fonts_localC

Call Device/GetLocalFontList. For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Inputs: target.

watchface_get_localC

Call Device/GetLocalClockInfo for current or explicit clock id. For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Inputs: target, clockId, parentItemId, parentClockId, +1 more.

watchface_get_screen_snapshotA

Capture the rendered screen for visual verification after create/patch/switch. Sends Device/GetScreenSnapshot, then downloads and validates the exact snapShotPath returned by AstroToo (currently BMP); TimesFrame retains its WebP fallback paths. Optional savePath writes the image locally for review. For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Inputs: target, waitMs, savePath, snapshotHttpPath.

watchface_get_store_market_listC

Call Device/GetStoreClockMarketList after device prefetch has populated in-memory store data. For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Inputs: target.

watchface_layout_suggestA

Return layout hints for a single disp id by combining disp-catalog metadata with aggregated typography (median size/x/y/w/h, frequent colors, alignment mode) mined from bundled marketplace templates. Use before authoring a new ItemList row or ItemPatchList.patch fragment — values are soft guidance, not firmware-enforced. Always clamp boxes to the logical canvas (typically 800×1280). For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Inputs: disp (required), model, target, canvasWidth, +1 more.

watchface_list_devicesA

List selectable TimesFrame 510/511/512, AstroToo 530, PIXOO64 90/92/96 and TimeGate 400/402 devices from https://app.divoom-gz.com/Device/ReturnSameLANDevice. Other hardware is filtered out. PIXOO64/TimeGate targets include Hardware and version-specific ports.

Inputs: port, timeoutMs.

watchface_onoff_screenB

Call Channel/OnOffScreen with OnOff (1=on, 0=off). For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Inputs: onOff (required), target.

watchface_patch_localA

Upsert the MCP-managed local watchface. The server injects its managed ClockId, reads that slot first, updates it when present, and creates it when missing if dialAssetsPath plus complete ItemList and ItemIdList are supplied. Callers do not provide a ClockId. Field-only updates use POST /divoom_api; asset updates use multipart. Prefer ItemPatchList for existing rows and do not include item_id inside patch.* unless explicitly renaming a slot. TimesFrame accepts a JPEG/WebP backdrop or clock_bg.tar.gz bundle. AstroToo accepts one JPEG/WebP backdrop only after element files are uploaded separately and bound through local:// FileId values. AstroToo rejects TAR/TGZ/ZIP and bundle_image. For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Inputs: target, fileName, itemList, itemIdList, +8 more.

watchface_protocol_quick_referenceB

Return concise operational constraints extracted from the public guide and skill. For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Inputs: model, target.

watchface_raw_commandA

Raw POST /divoom_api command wrapper. Command is required; payload object is merged with enforced ReturnCode=0. Raw Device/CreateLocalClock and Device/PatchLocalClockInfo payloads are restricted to ClockId 60000; use the dedicated create/patch tools for the full precheck and multipart upsert flow. For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Inputs: command (required), target, payload.

watchface_replace_dial_bg_fileB

POST /replace_clock_dial_bg using multipart (Device/ReplaceClockDialBgFile). Replaces the cached dial bitmap only and does not accept archives. Backdrop must be JPEG or WebP and less than 500 KiB. Required dimensions are selected from hardware: TimesFrame 800x1280, AstroToo 480x480. For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Inputs: imagePath (required), target, clockId, fileName, +2 more.

watchface_reset_local_then_cloudC

Call Device/ResetLocalClockFromServer. This deletes local sys-side files before optional cloud refresh. For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Inputs: clockId (required), target, parentItemId, parentClockId.

watchface_set_brightnessC

Call Channel/SetBrightness with Brightness. For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Inputs: brightness (required), target.

watchface_set_clock_selectA

Call Channel/SetClockSelectId with ClockId. TimesFrame queues a pair of identical requests in one serialized MCP operation so a manual selection suppresses an active traditional clock schedule for its current period; AstroToo sends it once. For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Inputs: clockId (required), target, sysUpdateTime.

watchface_template_searchA

Search the curated template library (divoom://templates/curated): ~20 marketplace-derived watchface skeletons with tags such as weather, lunar_calendar, split_time_digits, pixel_theme, asset_heavy. Prefer cloning an existing ItemList layout before inventing raw coordinates. Filters support tagsAll/tagsAny, bucket, clockIds, item-count bounds, and dispPresent (template must include that disp id). Set includeWatchface=false for a compact summary without the full ItemList payload. For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Inputs: limit, model, bucket, target, +8 more.

watchface_upload_fileA

AstroToo-only POST /upload_local_asset with one multipart file. Assets must be sent serially, one file per call, using Device/UploadLocalAsset metadata. Each success returns a temporary local:// FileId which must be bound by a successful create or patch; firmware then atomically moves the staging file into durable watchface storage. Unbound uploads are cleared on reboot and are never uploaded outward. TAR/TGZ/ZIP are rejected. The product photo/pixel POST /upload route is kept separate. TimesFrame generic /upload is blocked in MCP local-only mode; use create/patch multipart assets instead. For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Inputs: filePath (required), metadata (required), target, fileName, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.4/5.0

    Scored across 42 tools

    Disambiguation4/5

    The device-family prefixes (watchface_, pixoo64_, timegate_) and action-oriented suffixes make most tools clearly distinct. Within watchface_, however, watchface_patch_local and watchface_create_local_clock both upsert the managed local watchface, and the catalog/layout/search tools have some conceptual overlap, so a few selections may require careful reading.

    Naming Consistency4/5

    Names use consistent snake_case and predictable device prefixes across all four hardware families. Most action tools follow verb_noun patterns, but there are minor deviations such as watchface_template_search, watchface_clock_catalog, and watchface_disp_catalog that are noun-first or catalog-oriented.

    Tool Count3/5

    42 tools is heavy overall, driven by exposing separate operational tools for four distinct Divoom device families. Much of the duplication is justified by differing protocols, but the set is larger than ideal and could potentially consolidate common operations such as brightness, screen on/off, and command lists.

    Completeness4/5

    The surface covers device discovery, watchface authoring, catalog/layout guidance, rendering snapshots, brightness, screen control, and per-family command execution. There are minor gaps, such as PIXOO64 lacking a brightness readback tool and limited explicit lifecycle/delete operations, but core workflows are well supported.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • pixoo-mcp-server

      cyanheads
      A
      license
      A
      quality
      B
      maintenance
      Enables programmatic control of Divoom Pixoo LED matrices to display layered pixel art, animations, and hardware-rendered scrolling text. Users can compose complex visual scenes, push images, and manage device settings like brightness and channels through an LLM.
      8
      226 npm
      10
      Apache 2.0

    • @qirabot/mcp

      qirabot
      A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to control mobile and desktop devices with natural language, including running automation tasks, taking screenshots, and managing devices.
      6
      5 npm
      MIT

    • MCP Govee

      danjam
      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

    • mcp-server-awtrix

      klodnickik
      A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to control and display real-time notifications, telemetry, and custom apps on Ulanzi TC001 and compatible pixel clocks running Awtrix Light, including device management and declarative YAML-based metric polling.
      6
      MIT