Skip to main content
Glama
ulanzi-mcp

ulanzi-mcp

by Jelloeater

Ulanzi MCP Server

Test CodeQL Libraries.io dependency status for latest release

ulanzi-mcp PyPI - Status PyPI GitHub

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 sync

2. Configure

Copy .env.example to .env and set your clock IP:

ULANZI_HOSTS=http://192.168.1.100

For multiple clocks:

ULANZI_HOSTS=http://192.168.1.100,http://192.168.1.101

3. Use CLI

# Check configuration
ulanzi info

# Turn on display
ulanzi power on

# Show notification
ulanzi notify "Meeting in 5 minutes!"

# Set brightness
ulanzi brightness 200

4. 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

ULANZI_HOSTS

Clock address(es), comma-separated

http://192.168.1.100

ULANZI_USERNAME

HTTP auth username

(none)

ULANZI_PASSWORD

HTTP auth password

(none)

ULANZI_API_TIMEOUT

Request timeout (seconds)

10

ULANZI_MQTT_PREFIX

MQTT topic prefix

awtrix

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 pytest

License

MIT

Available Tools

20 tools
clear_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

    A4/5.0

    Scored across 20 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers