ulanzi-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ulanzi-mcp turn on the clock"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Ulanzi MCP Server
MCP server and CLI for the Ulanzi TC001 Smart Pixel Clock (AWTRIX3 firmware).
Features
MCP Server: Control your Ulanzi clock from AI assistants (Claude Desktop, Cursor, Windsurf)
CLI Tool: Command-line interface for scripting and automation
Multi-clock Support: Control multiple clocks from a single instance
Full API Coverage: Access all AWTRIX3 HTTP API endpoints
Related MCP server: idotmatrix-mcp
Quick Start
1. Install
cd ulanzi-mcp
uv sync2. Configure
Copy .env.example to .env and set your clock IP:
ULANZI_HOSTS=http://192.168.1.100For multiple clocks:
ULANZI_HOSTS=http://192.168.1.100,http://192.168.1.1013. Use CLI
# Check configuration
ulanzi info
# Turn on display
ulanzi power on
# Show notification
ulanzi notify "Meeting in 5 minutes!"
# Set brightness
ulanzi brightness 2004. Use with MCP (Claude Desktop)
Add to your Claude Desktop config:
{
"mcpServers": {
"ulanzi-mcp": {
"command": "uv",
"args": ["--directory", "/path/to/ulanzi-mcp", "run", "python", "-m", "ulanzi_mcp.server"]
}
}
}Environment Variables
Variable | Description | Default |
| Clock address(es), comma-separated |
|
| HTTP auth username | (none) |
| HTTP auth password | (none) |
| Request timeout (seconds) |
|
| MQTT topic prefix |
|
Available Tools/Commands
See docs/clock_spec.md for complete documentation.
Development
# Run MCP server in development mode
uv run mcp dev src/ulanzi_mcp/server.py
# Run CLI
ulanzi --help
# Run tests
uv run pytestLicense
MIT
Available Tools
20 toolsclear_indicatorsA
Clear all indicators from the clock.
Args: clock_index: Optional index of clock to target (0-based). Defaults to first clock.
Inputs: clock_index. Returns: object
delete_custom_appB
Delete a custom app from the clock.
Args: app_name: Name of the custom app to delete clock_index: Optional index of clock to target (0-based). Defaults to first clock.
Inputs: app_name (required), clock_index. Returns: object
dismiss_notificationB
Dismiss a held notification.
Args: clock_index: Optional index of clock to target (0-based). Defaults to first clock.
Inputs: clock_index. Returns: object
get_apps_in_loopA
Get list of all apps in the display rotation loop.
Returns the names of all apps that cycle through on the display.
Args: clock_index: Optional index of clock to target (0-based). Defaults to first clock.
Inputs: clock_index. Returns: object
get_available_effectsA
Get list of all available visual effects.
Returns available background effects that can be used with custom apps.
Args: clock_index: Optional index of clock to target (0-based). Defaults to first clock.
Inputs: clock_index. Returns: object
get_clock_settingsA
Get current clock settings.
Returns current display settings like brightness, colors, time format, etc.
Args: clock_index: Optional index of clock to target (0-based). Defaults to first clock.
Inputs: clock_index. Returns: object
get_clock_statsA
Get device statistics from the clock.
Returns battery level, RAM usage, uptime, and other device info.
Args: clock_index: Optional index of clock to target (0-based). Defaults to first clock.
Inputs: clock_index. Returns: object
next_appA
Switch to the next app in the display loop.
Args: clock_index: Optional index of clock to target (0-based). Defaults to first clock.
Inputs: clock_index. Returns: object
play_rtttlB
Play a RTTTL melody string directly.
Args: rtttl: RTTTL melody string (e.g., ":d=4,o=5,b=180:...") clock_index: Optional index of clock to target (0-based). Defaults to first clock.
Inputs: rtttl (required), clock_index. Returns: object
play_soundB
Play a RTTTL melody from the MELODIES folder.
Args: sound: Name of the sound file (without extension) clock_index: Optional index of clock to target (0-based). Defaults to first clock.
Inputs: sound (required), clock_index. Returns: object
previous_appA
Switch to the previous app in the display loop.
Args: clock_index: Optional index of clock to target (0-based). Defaults to first clock.
Inputs: clock_index. Returns: object
reboot_clockA
Reboot the clock.
Args: clock_index: Optional index of clock to target (0-based). Defaults to first clock.
Inputs: clock_index. Returns: object
set_brightnessA
Set the matrix brightness.
Args: brightness: Brightness level from 0 (off) to 255 (max) clock_index: Optional index of clock to target (0-based). Defaults to first clock.
Returns: Updated settings
Inputs: brightness (required), clock_index. Returns: object
set_indicatorA
Set a colored indicator on the clock.
Indicators are small notification signs displayed on specific areas:
Indicator 1: Upper right corner
Indicator 2: Right side
Indicator 3: Lower right corner
Args: indicator_id: Which indicator (1, 2, or 3) color: Color as hex string (e.g., "#FF0000") or RGB array blink: Blink interval in milliseconds fade: Fade interval in milliseconds clock_index: Optional index of clock to target (0-based). Defaults to first clock.
Inputs: indicator_id (required), color (required), blink, fade, +1 more. Returns: object
set_moodlightB
Set mood lighting on the clock.
Args: brightness: Brightness level 0-255 (default: 170) color: Color as hex string or RGB array kelvin: Color temperature in Kelvin clock_index: Optional index of clock to target (0-based). Defaults to first clock.
Inputs: brightness, color, kelvin, clock_index. Returns: object
set_powerA
Turn the matrix display on or off.
Args: power: True to turn on, False to turn off clock_index: Optional index of clock to target (0-based). Defaults to first clock.
Returns: Status of the power operation
Inputs: power (required), clock_index. Returns: object
set_sleepA
Send the clock to deep sleep mode.
The clock will wake up after the specified seconds or when the middle button is pressed.
Args: seconds: Number of seconds to sleep clock_index: Optional index of clock to target (0-based). Defaults to first clock.
Inputs: seconds (required), clock_index. Returns: object
show_custom_appA
Create or update a custom app on the clock.
Args: app_name: Unique name for this custom app text: Text to display duration: How long to show in seconds (default: 5) repeat: How many times to repeat scrolling (-1 = infinite, default) color: Text color as hex string or RGB array background: Background color icon: Icon name to display rainbow: Show text in rainbow colors (default: False) effect: Background effect name save: Save to flash memory (default: False) clock_index: Optional index of clock to target (0-based). Defaults to first clock.
Inputs: app_name (required), text, duration, repeat, +7 more. Returns: object
show_notificationA
Display a notification on the clock.
Args: text: Text to display duration: How long to show the notification in seconds (default: 5) color: Text color as hex string (e.g., "#FF0000") or RGB array icon: Icon name to display sound: Sound filename to play hold: Keep notification on screen until dismissed (default: False) wakeup: Wake up the matrix if it's off (default: False) stack: Stack with other notifications (default: True) clock_index: Optional index of clock to target (0-based). Defaults to first clock.
Inputs: text (required), duration, color, icon, +5 more. Returns: object
switch_to_appA
Switch to a specific app.
Args: app_name: Name of the app to switch to (e.g., 'Time', 'Date', 'Temperature', 'Humidity', 'Battery', or custom app name) clock_index: Optional index of clock to target (0-based). Defaults to first clock.
Inputs: app_name (required), clock_index. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Each tool has a distinct and clear purpose. Even related tools like play_rtttl and play_sound are differentiated by whether the melody is a string or file-based. No two tools overlap ambiguously.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., clear_indicators, get_clock_settings). The naming is predictable and easy to understand.
With 20 tools, the server covers the necessary operations for a smart clock without being excessive. Each tool addresses a specific function, making the surface well-scoped.
The tool set provides full coverage of clock management: settings, display, sound, notifications, custom apps, indicators, power, and navigation. No obvious gaps for common use cases.
Maintenance
Related MCP Connectors
MCP server for Uptrack uptime monitoring. Manage monitors and incidents from AI agents.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for AI dialogue using various LLM models via AceDataCloud
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for controlling Elgato Key Lights. Enables turning lights on/off, adjusting brightness and color temperature, applying presets, and triggering effects via Claude.13Apache 2.0
- FlicenseNot gradedqualityDmaintenanceAn MCP server that lets AI assistants draw pixel art on iDotMatrix LED displays over Bluetooth.1-
- AlicenseNot gradedqualityDmaintenanceMCP server for controlling an ESP32-C3 PetOS watch over BLE. Enables scanning, connecting, sending pet actions, and showing frames through MCP tools.MIT
- AlicenseAqualityDmaintenanceMCP server that enables AI agents to control Twinkly lights through natural language, supporting operations like on/off, color, brightness, and effects.1412 npmISC