MCP Server Awtrix: AI Agent Display Orchestrator for Ulanzi & Pixel Clocks

MCP Server Awtrix (mcp-server-awtrix) is an open-source Model Context Protocol (MCP) server and declarative metric orchestrator designed to give AI agents (Antigravity, Claude Desktop, Cursor, Cline, AutoGPT, etc.) full control over Ulanzi TC001 and compatible pixel matrix smart clocks running Awtrix Light.

It bridges conversational and autonomous AI agents with physical desktop displays, enabling:

• Instant Agent Alerts: Push ad-hoc status alerts, build failure notifications, and task completions to the pixel screen.
• Dynamic Carousel Apps: Register, update, and cycle through custom live telemetry apps (server health, SaaS metrics, revenue counters, build status).
• Declarative Metric Poller: Automate background API fetching and threshold formatting via YAML specifications without writing bespoke Python scripts.
• Hardware Telemetry & Control: Inspect battery levels, adjust matrix brightness, manage power states, and trigger custom sound cues.

---

Table of Contents

1. Product Requirements Document (PRD)
   • Problem Statement
   • Goals & Non-Goals
   • Target Personas & Use Cases
   • Functional Requirements
   • Non-Functional Requirements
2. System Architecture & Design
   • High-Level Architecture
   • Component Breakdown
   • Data Flow
3. MCP Tools Specification
4. Declarative App Engine (YAML Schema)
   • Example 1: CI/CD & Service Health (Checkly)
   • Example 2: Multi-Metric SaaS Dashboard
5. Quickstart & Installation
   • Prerequisites
   • Local Setup with uv / pip
   • MCP Client Configuration
6. Roadmap & Contributing
7. License

---

1. Product Requirements Document (PRD)

Problem Statement

Developers and power users running smart pixel clocks (like the Ulanzi TC001 with Awtrix Light) currently write fragmented, hardcoded Python or Bash cron scripts to query external APIs and update matrix apps.

When working with AI coding agents:

• Agents must generate and maintain raw imperative code for every metric.
• There is no standardized toolset for an AI agent to send real-time notifications or manage the display lifecycle.
• Secret management is error-prone, risking API key leaks in AI prompts and logs.
• There is no native fallback or validation for multi-segment text formatting and pixel icons.

Goals & Non-Goals

Goals

• Native MCP Interface: Provide a standard Model Context Protocol server exposing robust tools for notifications, custom apps, device management, and previews.
• Declarative Telemetry: Enable agents and humans to define metric polling rules in simple YAML files with built-in templating (Jinja2) and threshold styling.
• Secure Secret Isolation: Decouple sensitive credentials from prompt context using .env environment variable substitution.
• Zero-Downtime Hot-Reload: Automatically reflect changes made to YAML configuration files without service restarts.
• Reliable Fallbacks: Gracefully handle network outages, API rate limits, and offline display states.

Non-Goals

• Replacing the Awtrix Light firmware (this tool interacts exclusively with the official Awtrix Light REST/MQTT API).
• Complex multi-monitor tile synchronization (focus is on single or multi-instance standalone pixel clocks).

Target Personas & Use Cases

Persona	Scenario	How MCP Server Awtrix Helps
AI Coding Agent (e.g., Antigravity / Cursor)	Agent finishes a 10-minute test suite or autonomous task in the background.	Calls awtrix_notify tool to flash green with a checkmark icon and chime on the developer's desk.
DevOps / SRE Engineer	Wants to monitor production uptime, error budgets, or Checkly synthetic tests.	Drops a checkly.yaml declarative spec; orchestrator polls every 60s and turns red on failures.
SaaS Founder / Builder	Wants real-time MRR, new user signups, and support ticket counters cycling on desk.	Defines a declarative multi-metric app querying backend admin endpoints.

Functional Requirements

1. FR-1: Instant Notifications (/api/notify):
   • Support custom text, multi-segment colored text, icon ID, sound/RTTTL ringtones, priority hold, and duration.
2. FR-2: Custom Carousel Apps (/api/custom):
   • Ability to register, update, and remove named apps from the display loop.
   • Support rich text segment formatting ([{"t": "FAIL", "c": "FF0000"}, {"t": " (2/10)", "c": "FFFFFF"}]).
3. FR-3: Declarative Background Engine:
   • Built-in scheduler (asyncio / apscheduler) executing polling jobs defined in apps/*.yaml.
   • Templating engine supporting computed variables, arithmetic, and conditional expressions.
4. FR-4: Device State & Telemetry:
   • Query battery percentage, Wi-Fi RSSI, lux sensor, matrix state, and active apps.
   • Adjust brightness, sleep/wake status, and transitions.
5. FR-5: Dry-Run & Simulation:
   • Preview tool returning exact rendered JSON payloads and color validations prior to hardware submission.

Non-Functional Requirements

• Latency: Direct MCP tool executions must dispatch to Awtrix within $< 150\text{ms}$ on local networks.
• Resilience: Orchestrator retries failed API fetches with exponential backoff before marking an app degraded.
• Portability: Packaged as standard Python package with uv/pipx support, Docker container, and standalone CLI.

---

2. System Architecture & Design

High-Level Architecture

                                  ┌──────────────────────────┐
                                  │      AI Client/Host      │
                                  │ (Claude / Antigravity /  │
                                  │     Cursor / Cline)      │
                                  └────────────┬─────────────┘
                                               │
                                               │ stdio / SSE (MCP Protocol)
                                               ▼
┌────────────────────────────────────────────────────────────────────────────────────────┐
│                                  mcp-server-awtrix                                     │
│                                                                                        │
│  ┌───────────────────────┐   ┌──────────────────────────────┐   ┌───────────────────┐  │
│  │     MCP Interface     │   │      App Orchestrator        │   │   Config Watcher  │  │
│  │ (Tools / Resources)   │   │     (Async Scheduler)        │   │   (Hot-Reload)    │  │
│  └───────────┬───────────┘   └──────────────┬───────────────┘   └─────────┬─────────┘  │
│              │                              │                             │            │
│              ▼                              ▼                             ▼            │
│  ┌──────────────────────────────────────────────────────────────────────────────────┐  │
│  │                               Core Engine & Driver                               │  │
│  │  - Schema Validator (Pydantic)                                                   │  │
│  │  - Template & Expression Engine (Jinja2 / JSONPath)                              │  │
│  │  - Secret Resolver (.env)                                                        │  │
│  │  - Awtrix REST / WebSocket Client                                                │  │
│  └──────────────────────────────────────────┬───────────────────────────────────────┘  │
└─────────────────────────────────────────────┼──────────────────────────────────────────┘
                                              │
                                              │ HTTP REST (JSON)
                                              ▼
                                ┌──────────────────────────┐
                                │     Ulanzi TC001 Clock   │
                                │   (Awtrix Light Firmware)│
                                └──────────────────────────┘

Component Breakdown

1. MCP Interface Layer:
   • Implements Model Context Protocol server endpoints over stdio and SSE.
   • Exposes tools with strict JSON schemas and human-readable documentation for AI models.
2. Declarative Polling Engine:
   • Asynchronous worker managing task lifecycles for file-based app manifests.
   • Evaluates HTTP requests, extracts fields using JSONPath/expressions, and resolves display rules.
3. Awtrix Driver:
   • Encapsulates device communication, request deduplication, connection pooling, and error recovery.
4. Configuration & Security Layer:
   • Isolates sensitive tokens into .env. Config files reference variables via ${VAR_NAME} syntax.

---

3. MCP Tools Specification

AI Agents can execute the following MCP tools:

awtrix_notify

Pushes an immediate, high-priority notification to the screen (interrupts the current carousel).

{
  "text": "Build Failed: Backend API",
  "icon": "10558",
  "color": "FF0000",
  "duration": 8,
  "sound": "alarm",
  "rtttl": "beep:d=4,o=5,b=100:16e6,16e6",
  "wakeup": true
}

awtrix_upsert_app

Registers or updates a persistent custom app in the carousel loop.

{
  "name": "app_users",
  "text": [
    {"t": "1,420", "c": "FFFFFF"},
    {"t": " (+42)", "c": "00FF00"}
  ],
  "icon": "2058",
  "duration": 5,
  "lifetime": 300
}

awtrix_delete_app

Removes a custom app from the device cycle.

{
  "name": "app_users"
}

awtrix_get_device_state

Returns hardware statistics and current operational metrics.

Response:

{
  "online": true,
  "battery": 88,
  "charging": true,
  "lux": 140,
  "temp": 24,
  "ram_free": 128440,
  "active_app": "app_users",
  "brightness": 120
}

awtrix_set_settings

Configures device parameters such as brightness, matrix toggle, and transition speeds.

{
  "brightness": 80,
  "power": true
}

awtrix_test_render

Dry-run helper that parses expressions and returns the rendered payload without pushing to hardware.

---

4. Declarative App Engine (YAML Schema)

Rather than maintaining custom Python scripts, place .yaml manifests in the apps/ directory.

Example 1: Service Health (Checkly)

apps/checkly.yaml

app_id: "checkly"
name: "checkly_status"
enabled: true
interval_seconds: 60

source:
  type: "http"
  url: "https://api.checklyhq.com/v1/checks"
  headers:
    Authorization: "Bearer ${CHECKLY_API_KEY}"
    X-Checkly-Account: "${CHECKLY_ACCOUNT_ID}"

transform:
  total: "len(data)"
  failures: "sum(1 for c in data if c.get('hasFailures'))"
  degraded: "sum(1 for c in data if c.get('isDegraded') and not c.get('hasFailures'))"

display:
  - condition: "failures > 0"
    icon: "10558"
    notify: true
    text:
      - { text: "FAIL ", color: "FF0000" }
      - { text: "({{failures}}/{{total}})", color: "FFFFFF" }

  - condition: "degraded > 0"
    icon: "10558"
    text:
      - { text: "WARN ", color: "FFA500" }
      - { text: "({{degraded}}/{{total}})", color: "FFFFFF" }

  - condition: "default"
    icon: "483"
    text:
      - { text: "UP ", color: "00FF00" }
      - { text: "({{total}})", color: "FFFFFF" }

Example 2: Multi-Metric SaaS Dashboard

apps/saas_metrics.yaml

app_id: "saas_metrics"
interval_seconds: 120

source:
  type: "http"
  url: "https://api.example.com/v1/admin/metrics"
  headers:
    X-API-Secret: "${SAAS_METRICS_API_SECRET}"

sub_apps:
  - name: "app_users"
    icon: "2058"
    text:
      - { text: "{{data.users_total}}", color: "FFFFFF" }
      - { text: " (+{{data.new_users_last_week}})", color: "00FF00" }

  - name: "app_premium"
    icon: "5336"
    text:
      - { text: "{{data.users_premium}}", color: "FFFFFF" }
      - { text: " (+{{data.new_users_premium_last_week}})", color: "FFD700" }

  - name: "app_orders"
    icon: "21072"
    text:
      - { text: "{{data.orders_total}}", color: "FFFFFF" }
      - { text: " (+{{data.new_orders_last_week}})", color: "00FF00" }

  - name: "app_support"
    icon: "10558"
    show_if: "data.tickets_open > 0"
    text:
      - { text: "{{data.tickets_open}}", color: "FF0000" }

---

5. Quickstart & Installation

Prerequisites

• Python 3.10 or higher
• Ulanzi TC001 (or compatible device) flashed with Awtrix Light Firmware connected to your Wi-Fi network.

Local Setup with uv / pip

# Clone the repository
git clone https://github.com/klodnickik/mcp-server-awtrix.git
cd mcp-server-awtrix

# Copy example environment configuration
cp .env.example .env

# Edit device address and API keys in .env
# AWTRIX_BASE_URL=http://awtrix3.local

Run the MCP server locally over stdio:

# Using uv (recommended)
uv run mcp-server-awtrix

# Or standard pip
pip install -e .
python -m awtrix_mcp

Or over SSE (HTTP), for clients that connect remotely:

uv run mcp-server-awtrix --transport sse --host 0.0.0.0 --port 8000

Running Tests

uv sync --group dev
uv run pytest

Docker & Docker Compose Setup

Run using Docker Compose:

# 1. Clone & prepare environment
git clone https://github.com/klodnickik/mcp-server-awtrix.git
cd mcp-server-awtrix
cp .env.example .env

# 2. Start the MCP Server (SSE on port 8000) and Metric Daemon
docker compose up -d

# Or start only the metric poller daemon:
docker compose up -d metric-daemon

# View live logs:
docker compose logs -f

MCP Client Configuration

1. Google Antigravity

Add to your mcp_servers.json:

{
  "mcpServers": {
    "awtrix": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-server-awtrix", "run", "mcp-server-awtrix"],
      "env": {
        "AWTRIX_BASE_URL": "http://awtrix3.local"
      }
    }
  }
}

2. Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "awtrix": {
      "command": "python",
      "args": ["-m", "awtrix_mcp"],
      "env": {
        "AWTRIX_BASE_URL": "http://awtrix3.local"
      }
    }
  }
}

3. Cursor

In Cursor Settings $\rightarrow$ Features $\rightarrow$ MCP Servers $\rightarrow$ Add Server:

• Name: awtrix
• Type: command
• Command: uv --directory /path/to/mcp-server-awtrix run mcp-server-awtrix

---

6. Roadmap & Contributing

• [x] Core MCP Tools specification and design
• [x] Declarative YAML orchestration schema
• [x] MCPServer (mcp v2) implementation with async HTTP client
• [ ] Live visual web preview for matrix pixel art
• [ ] MQTT Transport layer support (optional alternative to REST)
• [ ] Home Assistant service discovery export

Contributions are welcome! Please submit a PR or open an issue for feature discussions.

---

7. License

Distributed under the MIT License. See LICENSE for more information.