MCP Server Awtrix: KI-Agenten-Display-Orchestrator für Ulanzi- und Pixel-Clocks

MCP Server Awtrix (mcp-server-awtrix) ist ein Open-Source-Model Context Protocol (MCP)-Server und deklarativer Metrik-Orchestrator, der KI-Agenten (Antigravity, Claude Desktop, Cursor, Cline, AutoGPT usw.) die volle Kontrolle über Ulanzi TC001 und kompatible Pixel-Matrix-Smart-Clocks mit Awtrix Light gibt.

Er verbindet konversationelle und autonome KI-Agenten mit physischen Desktop-Displays und ermöglicht:

• Sofortige Agenten-Benachrichtigungen: Ad-hoc-Statusmeldungen, Build-Fehlerhinweise und Aufgabenabschlüsse auf den Pixel-Bildschirm pushen.

• Dynamische Karussell-Apps: Benutzerdefinierte Live-Telemetrie-Apps (Servergesundheit, SaaS-Metriken, Umsatzzähler, Build-Status) registrieren, aktualisieren und durchlaufen.

• Deklarativer Metrik-Poller: Hintergrund-API-Abrufe und Schwellwertformatierung per YAML-Spezifikation automatisieren, ohne individuelle Python-Skripte zu schreiben.

• Hardware-Telemetrie & Steuerung: Batteriestand prüfen, Matrix-Helligkeit anpassen, Energiestatus verwalten und benutzerdefinierte Sound-Signale auslösen.

Inhaltsverzeichnis

1. Produktanforderungsdokument (PRD)

   • Problemstellung

   • Ziele & Nicht-Ziele

   • Zielpersonas & Anwendungsfälle

   • Funktionale Anforderungen

   • Nicht-funktionale Anforderungen

2. Systemarchitektur & Design

   • Hochrangige Architektur

   • Komponentenaufschlüsselung

   • Datenfluss

3. MCP-Tools-Spezifikation

4. Deklarative App-Engine (YAML-Schema)

   • Beispiel 1: CI/CD & Service-Gesundheit (Checkly)

   • Beispiel 2: Multi-Metrik-SaaS-Dashboard

5. Schnellstart & Installation

   • Voraussetzungen

   • Lokale Einrichtung mit uv / pip

   • MCP-Client-Konfiguration

6. Roadmap & Mitwirken

7. Lizenz

Related MCP server: pixoo-mcp-server

1. Produktanforderungsdokument (PRD)

Problemstellung

Entwickler und Power-User, die intelligente Pixel-Clocks (wie die Ulanzi TC001 mit Awtrix Light) betreiben, schreiben derzeit fragmentierte, hartcodierte Python- oder Bash-Cron-Skripte, um externe APIs abzufragen und Matrix-Apps zu aktualisieren.

Bei der Arbeit mit KI-Codierungsagenten:

• Agenten müssen für jede Metrik rohen imperativen Code generieren und pflegen.

• Es gibt kein standardisiertes Werkzeugset, mit dem ein KI-Agent Echtzeit-Benachrichtigungen senden oder den Display-Lebenszyklus verwalten kann.

• Die Geheimnisverwaltung ist fehleranfällig und riskiert API-Schlüssellecks in KI-Prompts und Logs.

• Es gibt keinen nativen Fallback oder Validierung für mehrsegmentige Textformatierung und Pixel-Icons.

Ziele & Nicht-Ziele

Ziele

• Native MCP-Schnittstelle: Einen standardmäßigen Model Context Protocol-Server bereitstellen, der robuste Tools für Benachrichtigungen, benutzerdefinierte Apps, Geräteverwaltung und Vorschauen bietet.

• Deklarative Telemetrie: Agenten und Menschen ermöglichen, Metrik-Polling-Regeln in einfachen YAML-Dateien mit integrierter Templating (Jinja2) und Schwellwert-Styling zu definieren.

• Sichere Geheimnis-Isolation: Sensible Anmeldeinformationen mithilfe von .env-Umgebungsvariablen-Substitution vom Prompt-Kontext entkoppeln.

• Zero-Downtime-Hot-Reload: Änderungen an YAML-Konfigurationsdateien automatisch ohne Dienstneustart widerspiegeln.

• Zuverlässige Fallbacks: Netzwerkausfälle, API-Ratenbegrenzungen und Offline-Display-Zustände elegant behandeln.

Nicht-Ziele

• Ersetzen der Awtrix-Light-Firmware (dieses Tool interagiert ausschließlich mit der offiziellen Awtrix-Light-REST/MQTT-API).

• Komplexe Multi-Monitor-Kachelsynchronisierung (Fokus liegt auf einzelnen oder mehreren eigenständigen Pixel-Clocks).

Zielpersonas & Anwendungsfälle

Funktionale Anforderungen

1. FR-1: Sofortige Benachrichtigungen (/api/notify):

   • Unterstützung für benutzerdefinierten Text, mehrsegmentigen farbigen Text, Icon-ID, Sound/RTTTL-Klingeltöne, Prioritäts-Hold und Dauer.

2. FR-2: Benutzerdefinierte Karussell-Apps (/api/custom):

   • Möglichkeit, benannte Apps im Display-Loop zu registrieren, zu aktualisieren und zu entfernen.

   • Unterstützung für Rich-Text-Segmentformatierung ([{"t": "FAIL", "c": "FF0000"}, {"t": " (2/10)", "c": "FFFFFF"}]).

3. FR-3: Deklarative Hintergrund-Engine:

   • Integrierter Scheduler (asyncio / apscheduler), der Polling-Jobs aus apps/*.yaml ausführt.

   • Templating-Engine mit Unterstützung für berechnete Variablen, Arithmetik und bedingte Ausdrücke.

4. FR-4: Gerätezustand & Telemetrie:

   • Batterieprozentsatz, Wi-Fi-RSSI, Lux-Sensor, Matrix-Zustand und aktive Apps abfragen.

   • Helligkeit, Schlaf-/Wachstatus und Übergänge anpassen.

5. FR-5: Trockenlauf & Simulation:

   • Vorschau-Tool, das exakte gerenderte JSON-Payloads und Farbvalidierungen vor der Hardware-Übermittlung zurückgibt.

Nicht-funktionale Anforderungen

• Latenz: Direkte MCP-Tool-Ausführungen müssen Awtrix innerhalb von $< 150\text{ms}$ in lokalen Netzwerken erreichen.

• Resilienz: Der Orchestrator wiederholt fehlgeschlagene API-Abrufe mit exponentiellem Backoff, bevor er eine App als degradiert markiert.

• Portabilität: Als Standard-Python-Paket mit uv/pipx-Unterstützung, Docker-Container und eigenständigem CLI verpackt.

2. Systemarchitektur & Design

Hochrangige Architektur

                                  ┌──────────────────────────┐
                                  │      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)│
                                └──────────────────────────┘

Komponentenaufschlüsselung

1. MCP-Schnittstellenschicht:

   • Implementiert Model Context Protocol-Serverendpunkte über stdio und SSE.

   • Stellt Tools mit strengen JSON-Schemas und menschenlesbarer Dokumentation für KI-Modelle bereit.

2. Deklarative Polling-Engine:

   • Asynchroner Worker, der Task-Lebenszyklen für dateibasierte App-Manifeste verwaltet.

   • Wertet HTTP-Anfragen aus, extrahiert Felder mithilfe von JSONPath/Ausdrücken und löst Anzeigeregeln auf.

3. Awtrix-Treiber:

   • Kapselt Gerätekommunikation, Anfrage-Deduplizierung, Verbindungspooling und Fehlerbehebung.

4. Konfigurations- & Sicherheitsschicht:

   • Isoliert sensible Tokens in .env. Konfigurationsdateien referenzieren Variablen über die ${VAR_NAME}-Syntax.

3. MCP-Tools-Spezifikation

KI-Agenten können die folgenden MCP-Tools ausführen:

awtrix_notify

Sendet eine sofortige, hochpriorisierte Benachrichtigung an den Bildschirm (unterbricht das aktuelle Karussell).

{
  "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

Registriert oder aktualisiert eine dauerhafte benutzerdefinierte App im Karussell-Loop.

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

awtrix_delete_app

Entfernt eine benutzerdefinierte App aus dem Gerätezyklus.

{
  "name": "app_users"
}

awtrix_get_device_state

Gibt Hardware-Statistiken und aktuelle Betriebsmetriken zurück.

Antwort:

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

awtrix_set_settings

Konfiguriert Geräteparameter wie Helligkeit, Matrix-Schalter und Übergangsgeschwindigkeiten.

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

awtrix_test_render

Trockenlauf-Hilfsprogramm, das Ausdrücke parst und das gerenderte Payload zurückgibt, ohne es an die Hardware zu senden.

4. Deklarative App-Engine (YAML-Schema)

Anstatt benutzerdefinierte Python-Skripte zu pflegen, legen Sie .yaml-Manifeste im Verzeichnis apps/ ab.

Beispiel 1: Service-Gesundheit (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" }

Beispiel 2: Multi-Metrik-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. Schnellstart & Installation

Voraussetzungen

• Python 3.10 oder höher

• Ulanzi TC001 (oder kompatibles Gerät) mit Awtrix Light Firmware geflasht und mit Ihrem Wi-Fi-Netzwerk verbunden.

Lokale Einrichtung mit 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

Führen Sie den MCP-Server lokal über stdio aus:

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

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

Docker- & Docker-Compose-Einrichtung

Führen Sie mit Docker Compose aus:

# 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-Konfiguration

1. Google Antigravity

Fügen Sie zu Ihrer mcp_servers.json hinzu:

{
  "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

Fügen Sie zu claude_desktop_config.json hinzu:

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

3. Cursor

In Cursor-Einstellungen $\rightarrow$ Features $\rightarrow$ MCP-Server $\rightarrow$ Server hinzufügen:

• Name: awtrix

• Typ: command

• Befehl: uv --directory /path/to/mcp-server-awtrix run mcp-server-awtrix

6. Roadmap & Mitwirken

• Kern-MCP-Tools-Spezifikation und Design

• Deklaratives YAML-Orchestrierungsschema

• FastMCP-Implementierung mit asynchronem HTTP-Client

• Live-Web-Vorschau für Matrix-Pixelkunst

• MQTT-Transportschicht-Unterstützung (optionale Alternative zu REST)

• Home-Assistant-Dienstfindungs-Export

Beiträge sind willkommen! Bitte reichen Sie einen PR ein oder eröffnen Sie ein Issue für Feature-Diskussionen.

7. Lizenz

Verteilt unter der MIT-Lizenz. Siehe LICENSE für weitere Informationen.