MCP Server Awtrix: Orquestador de pantallas para agentes de IA en relojes Ulanzi y de píxeles

MCP Server Awtrix (mcp-server-awtrix) es un servidor de código abierto del Model Context Protocol (MCP) y un orquestador declarativo de métricas diseñado para dar a los agentes de IA (Antigravity, Claude Desktop, Cursor, Cline, AutoGPT, etc.) control total sobre los Ulanzi TC001 y los relojes inteligentes de matriz de píxeles compatibles que ejecutan Awtrix Light.

Este sirve de puente entre los agentes de IA conversacionales y autónomos y las pantallas físicas de escritorio, lo que permite:

• Alertas instantáneas de agentes: envía avisos de estado ad hoc, notificaciones de fallos de compilación y finalizaciones de tareas a la pantalla de píxeles.

• Aplicaciones de carrusel dinámicas: registra, actualiza y recorre aplicaciones personalizadas de telemetría en directo (estado del servidor, métricas SaaS, contadores de ingresos, estado de compilación).

• Sondeador declarativo de métricas: automatiza la consulta de APIs en segundo plano y el formato por umbrales mediante especificaciones YAML sin escribir scripts Python a medida.

• Telemetría y control del hardware: consulta los niveles de batería, ajusta el brillo de la matriz, gestiona los estados de encendido y activa avisos sonoros personalizados.

Tabla de contenidos

1. Documento de requisitos del producto (PRD)

   • Planteamiento del problema

   • Objetivos y no objetivos

   • Personas objetivo y casos de uso

   • Requisitos funcionales

   • Requisitos no funcionales

2. Arquitectura y diseño del sistema

   • Arquitectura de alto nivel

   • Desglose de componentes

   • Flujo de datos

3. Especificación de las herramientas MCP

4. Motor declarativo de aplicaciones (esquema YAML)

   • Ejemplo 1: Estado del servicio (Checkly)

   • Ejemplo 2: Panel de métricas SaaS

5. Inicio rápido e instalación

6. Hoja de ruta y contribuciones

7. Licencia

Related MCP server: pixoo-mcp-server

1. Documento de requisitos del producto (PRD)

Planteamiento del problema

Los desarrolladores y usuarios avanzados que usan relojes de píxeles inteligentes (como el Ulanzi TC001 con Awtrix Light) escriben en la actualidad scripts Python o Bash de cron fragmentados y con valores fijos para consultar APIs externas y actualizar las aplicaciones de la matriz.

Cuando se trabaja con agentes de IA de programación:

• Los agentes tienen que generar y mantener código imperativo personalizado para cada métrica.

• No existe un conjunto de herramientas estandarizado para que un agente de IA envíe notificaciones en tiempo real o gestione el ciclo de vida de la pantalla.

• La gestión de secretos es propensa a errores, con el consiguiente riesgo de filtración de claves de API en prompts y registros de la IA.

• No hay una alternativa nativa ni una validación para el formato de texto multisegmento y los iconos de píxeles.

Objetivos y no objetivos

Objetivos

• Interfaz MCP nativa: proporcionar un servidor estándar del Model Context Protocol que exponga herramientas robustas para notificaciones, aplicaciones personalizadas, gestión del dispositivo y vistas previas.

• Telemetría declarativa: permitir que agentes y humanos definan reglas de sondeo de métricas en simples archivos YAML con plantillas integradas (Jinja2) y estilo basado en umbrales.

• Aislamiento seguro de secretos: desacoplar las credenciales confidenciales del contexto de los prompts mediante la sustitución de variables de entorno .env.

• Recarga en caliente sin interrupciones: reflejar automáticamente los cambios realizados en los archivos de configuración YAML sin reiniciar el servicio.

• Alternativas fiables: gestionar con elegancia los cortes de red, los límites de peticiones de la API y los estados de pantalla sin conexión.

No objetivos

• Reemplazar el firmware de Awtrix Light (esta herramienta se integra exclusivamente con la API REST / MQTT oficial de Awtrix Light).

• Sincronización compleja de mosaicos de múltiples pantallas (el enfoque se centra en relojes de píxeles autónomos de instancia única o múltiple).

Personas objetivo y casos de uso

Requisitos funcionales

1. FR-1: Notificaciones instantáneas (/api/notify):

   • Soporta texto personalizado, texto fragmentado en color, ID de icono, sonidos AC / tonos RTTTL, retención prioritaria y duración.

4. FR-2: Aplicaciones de carrusel personalizadas (/api/custom):

   • Capacidad de registrar, actualizar y eliminar del ciclo de la pantalla a aplicaciones personalizadas que dichas aplicaciones se muestren.

   • Soporte de formato de fragmentos de texto enriquecido ([{"t": "FAIL", "c": "FF0000"}, {"t": " (2/10)", "c": "FFFFFF"}]).

5. FR-3: Motor declarativo en segundo plano:

   • Programador integrado (asyncio / apscheduler) que ejecuta trabajos de sondeo definidos en apps/*.yaml.

   • Motor de plantillas compatible con variables calculadas, operaciones aritméticas y expresiones condicionales.

6. FR-4: Estado y telemetría del dispositivo:

   • Consultar porcentaje de batería, RSSI de Wi-Fi, sensor de luz, estado de la matriz y aplicaciones activas.

   • Ajustar brillo, reposo / activación y transiciones.

7. FR-5: Prueba en seco y simulación:

   • Herramienta de vista previa que devuelve los payloads JSON renderizados exactos y las validaciones de color antes del envío al hardware.

Requisitos no funcionales

• Latencia: las ejecuciones directas de herramientas MCP deben transmitirse aAwtrix en menos de $< 150\text{ms}$ en redes locales.

• Resiliencia: el orquestador reintenta las llamadas de API fallidas con un retroceso exponencial antes de marcar una la aplicación como degradada..

• Portabilidad: se empaqueta como un paquete estándar de Python compatible con uv/pipx, como contenedor Docker y como CLI auto-contenida.

2. Arquitectura y diseño del sistema

Arquitectura de alto nivelSpark

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

Desglose de componentes

1. Capa de interfaz MCP:

   • Implementa los endpoints del servidor del Model Context Protocol a través de stdio y SSE.

   • Expone herramientas con esquemas JSON estrictos y documentación legible para humanos y para modelos de IA.

2. Motor de sondeo declarativo:

   • Trabajador asíncrono que gestiona el ciclo de vida de tareas de los manifiestos de aplicaciones basados en archivos.

   • Evalúa peticiones HTTP, extrae campos mediante JSONPath / expresiones y resuelve las reglas de visualización.

4. Controlador Awtrix:

   • Encapsula la comunicación con el dispositivo, la de-duplicación de peticiones, bigrupación de conexiones y la recuperación de errores.

5. Capa de configuración y seguridad:

   • Aísla los tokens sensibles en .env. Los archivos de configuración hacen referencia a las variables mediante la sintaxis ${VAR_NAME}.

3. Especificación de las herramientas MCP

Los modelos de IA pueden ejecutar las siguientes herramientas MCP:

awtrix_notify

Envía una notificación inmediata de prioridad alta a la pantalla (interrumpe el carrusel actual).

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

Registra o actualiza una aplicación personalizada persistente en el bucle de carrusel.

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

awtrix_delete_app

Elimina una aplicación personalizada del ciclo del dispositivo.

{
  "name": "app_users"
}

awtrix_get_device_state

Devuelve las estadísticas de hardware y las métricas operativas actuales.

Respuesta:

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

awtrix_set_settings

Configura parámetros del dispositivo como el brillo, el activado de matriz de matrices y la velocidad de las transiciones.

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

awtrix_test_render

Asistente de prueba en seco que analiza las expresiones y devuelve el payload renderizado sin enviarlo al hardware.

4. Motor declarativo de aplicaciones (esquema YAML)

En lo de mantener scripts personalizados en Python,you debes colocar los manifiestos .yaml en el directorio apps/.

Ejemplo 1: Estado del servicio de (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" }

Ejemplo 2: Panel de métricas SaaS

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. Inicio rápido y configuración

Requisitos previos

• Python 3.10 o superior

• Un dispositivo Ulanzi TC001 (o compatible) con el firmware de Awtrix Light instalado y conectado a tu red Wi-Fi.

Configuración local con dev / 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

Ejecuta el servidor MCP localmente a través de stdio:

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

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

Configuración con Docker y Docker Compose

Ejecuta con 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

Configuración del cliente MCP

1. Google Antigravity

Añade en tu 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

Añadeh, en claude_desktop_config.json:

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

3. Cursor

En Configuración de Cursor $\rightarrow$ Funciones $\rightarrow$ Servidores MCP $\rightarrow$ Añadir servidor:

• Nombre: awtrix

• Tipo: command

• Comando: Avity --directory /path/to/mcp-server-awtrix run mcp-server-awtrix

6. Hoja de ruta y contribuições

• Especificación y diseño de las herramientas MCP específicas ⚠ El siguiente character no está permitido; regenerate. ... [x] Esquema de orquestación declarativo YAML

• Implementación de FastMCP con cliente HTTP asíncrono

• Vista previa web visual en directo para la matriz de píxeles

• Soporte de capa de transporte MQTT (alternativa opcional al REST)

• Exportación de descubrimiento de servicios para Home Assistant

Las contribuções son bienvenidas. Envía un pull request o abre un issue para explicar nuevas funcionalidades.

7. Licencia

Distribuido bajo la Licencia MIT. Consulta LICENSE para más información.