How do I use mcp-server-awtrix?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-server-awtrix Notify my Awtrix clock: 'Build passed' in green" 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.

de en es ja ko ru zh

mcp-server-awtrix

by klodnickik

Overview Schema Source Related Servers Score Discussions Admin

Python

Hybrid

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

License: MIT MCP Protocol Python 3.10+ Awtrix Light

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.

Related MCP server: pixoo-mcp-server

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

FR-1: Instant Notifications (/api/notify):
- Support custom text, multi-segment colored text, icon ID, sound/RTTTL ringtones, priority hold, and duration.
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"}]).
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.
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.
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: A failed source fetch is logged and skipped for that cycle; the next scheduled poll (per interval_seconds) retries automatically. No exponential backoff or explicit "degraded" state is applied to source fetches.
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 / restricted Python evaluator)           │  │
│  │  - Secret Resolver (.env)                                                        │  │
│  │  - Awtrix REST / WebSocket Client                                                │  │
│  └──────────────────────────────────────────┬───────────────────────────────────────┘  │
└─────────────────────────────────────────────┼──────────────────────────────────────────┘
                                              │
                                              │ HTTP REST (JSON)
                                              ▼
                                ┌──────────────────────────┐
                                │     Ulanzi TC001 Clock   │
                                │   (Awtrix Light Firmware)│
                                └──────────────────────────┘

Component Breakdown

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.
Declarative Polling Engine:
- Asynchronous worker managing task lifecycles for file-based app manifests.
- Evaluates HTTP requests, extracts fields using a sandboxed expression evaluator (see §4), and resolves display rules.
Awtrix Driver:
- Encapsulates device communication, request deduplication, connection pooling, and error recovery.
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:

{
  "bat": 88,
  "charging": true,
  "lux": "140",
  "ram": 128440,
  "temp": "24",
  "active_app": "app_users"
}

NOTE

charging and active_app are unconfirmed on certain physical hardware revisions and are omitted by the server when null or unsupported by the device firmware.

`awtrix_set_settings`

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

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

NOTE

transitions (ATRANS) is unconfirmed on certain hardware versions and defaults to None.

`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" }

source also supports HTTP Basic Auth as an alternative to header-based credentials:

source:
  type: "http"
  url: "https://api.example.com/v1/private"
  auth:
    username: "${API_USERNAME}"
    password: "${API_PASSWORD}"

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

Run the metric poller daemon locally (polls apps/*.yaml in the background):

uv run awtrix-daemon --apps-dir apps

Validate a manifest without running the daemon (useful before deploying a new apps/*.yaml; exits 0 if all checked manifests are valid and have unique app_ids, 1 otherwise):

uv run awtrix-daemon validate apps/checkly.yaml
# or validate every manifest under --apps-dir:
uv run awtrix-daemon validate

Running Tests

uv sync --group dev
uv run pytest
# with coverage:
uv run pytest --cov --cov-report=term-missing

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

Multi-arch builds (Raspberry Pi / arm64):

# One-time setup for a buildx builder that supports multiple platforms
docker buildx create --use

docker buildx build --platform linux/amd64,linux/arm64 -t <you>/mcp-server-awtrix:local .

Prebuilt multi-arch images (linux/amd64 + linux/arm64) are also published to ghcr.io/klodnickik/mcp-server-awtrix by CI on every push to main and on version tags, so NAS/Pi/cloud users can docker pull instead of building locally.

Health check: the mcp-server container exposes GET http://localhost:8000/health, which returns {"status": "ok"} when the server is up. The metric-daemon container has no HTTP surface, so it's checked instead via a heartbeat file written every 30s and considered stale after 90s. CONTAINER_ROLE and DAEMON_HEARTBEAT_FILE are internal compose-wiring environment variables used to pick the right healthcheck per service — they don't need to be set in .env.

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 → Features → MCP Servers → Add Server:

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

6. Roadmap & Contributing

Core MCP Tools specification and design
MCPServer (mcp v2) implementation with async HTTP client
Declarative YAML metric poller daemon (awtrix-daemon) with hot-reload
Production-grade multi-arch Docker and Compose deployment
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 review our Contributing Guide and Changelog before submitting a pull request.

7. License

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

Available Tools

6 tools

awtrix_delete_appA

DestructiveIdempotent

Remove a custom app from the display cycle by name.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare idempotentHint and destructiveHint, so the core behavioral safety profile is covered. The description adds context beyond the annotations by specifying exactly what is destroyed or affected: a custom app's presence in the display cycle. No contradiction exists between the description and annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no filler. It states the action, target, scope, and parameter mechanism efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple: one required parameter, an output schema is present, and annotations cover idempotency and destructive behavior. The description covers the essential target and parameter. Minor gaps remain around exact-name matching and the precise meaning of 'from the display cycle', but nothing critical is missing for basic invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description only indicates that removal happens 'by name'. This adds meaning beyond the raw schema by relating the 'name' parameter to the custom app identifier, but it does not clarify expected format, uniqueness, or matching behavior. For a single simple parameter, this is adequate but minimal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Remove'), identifies the exact resource ('a custom app from the display cycle'), and specifies the selection mechanism ('by name'). This clearly distinguishes it from sibling tools like awtrix_upsert_app, which creates or updates an app rather than deleting it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance is given about when to use this tool versus alternatives, nor are exclusions or prerequisites mentioned. The intended use is only implied by the tool's name and purpose, not stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

awtrix_get_device_stateA

Read-onlyIdempotent

Return current AWTRIX hardware metrics: battery, lux, temperature, active app (if available).

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds useful behavioral nuance by saying 'current' and 'if available,' signaling that values may change over time and that the active app field can be absent. This is meaningful context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, well-structured sentence states the action and the list of returned metrics with no filler. The most important scoping word ('current') appears upfront, and the optionality of the active app is handled compactly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters, an output schema present, and annotations covering idempotence/read-only behavior, the description is sufficient for an agent to invoke the tool correctly. It states exactly what hardware metrics will be returned and does not need to cover return formatting because the output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the description has no parameter burden to carry. The baseline for zero-parameter tools is 4, and there is nothing here that reduces the score; the description instead clarifies what the returned metrics are.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Return') and names the exact resource: current AWTRIX hardware metrics (battery, lux, temperature, active app). It clearly distinguishes this read-only tool from the mutating/action siblings like awtrix_delete_app, awtrix_notify, and awtrix_upsert_app without needing to open the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes it clear this is the status/read tool by saying 'Return current...' while all sibling tools are actions or mutations. It does not explicitly state when not to use it, but the context is clear enough that an agent would select this for reading hardware state rather than for changing anything.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

awtrix_notifyB

Push an instant, high-priority notification to the AWTRIX display.

ParametersJSON Schema

Name	Required	Description	Default
`hold`	No
`icon`	No
`text`	Yes
`color`	No
`rtttl`	No
`sound`	No
`stack`	No
`wakeup`	No
`duration`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already communicate open-world behavior and non-idempotency, and the description adds that the notification is pushed instantly with high priority. It does not disclose auth needs, rate limits, or stacking/replacement behavior, but it does not contradict the annotations either.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence that states the essential action and destination with no filler. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The core call is clear, but the description is minimal for a tool with 9 parameters and several sibling tools. It does not explain optional parameter relationships, duplicate-notification behavior, or when to prefer test_render; the presence of an output schema and annotations softens but does not fill these gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description provides no prose about any of the 9 parameters. The schema's names and defaults are somewhat informative, but the description fails to compensate for the coverage gap, such as what 'text' should contain or how icon/color/sound values are formatted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly names the action ('Push'), the object ('notification'), and the destination ('AWTRIX display'), and adds the distinguishing 'instant, high-priority' quality. This makes it easy to separate from sibling tools that manage apps, settings, or device state.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use this tool versus alternatives such as awtrix_test_render or awtrix_upsert_app. The phrase 'instant, high-priority' weakly implies a use case, but the agent has to infer the right context from the tool name and siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

awtrix_set_settingsA

Idempotent

Configure display brightness, transition animations, and screen power state.

ParametersJSON Schema

Name	Required	Description	Default
`power`	No
`brightness`	No
`transitions`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the description is not required to restate safety behavior. The description adds a bit of context by listing what settings are affected, but it does not disclose side effects, persistence, or range constraints beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, compact sentence that states the action and the key areas affected. It is front-loaded with the verb and wastes no words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple three-parameter settings tool with an output schema and safety-related annotations, the description is mostly sufficient. It could mention that all parameters are optional and independently updatable, but the schema already conveys that through defaults and nullability.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description bears the responsibility for explaining parameters. It only paraphrases the property names (brightness, transitions, power) without adding meaning about value ranges, units, null semantics, or the effect of each flag. The schema reveals defaults but little explanatory content.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Configure') and clearly identifies the resource (display settings) while naming the three configurable areas: brightness, transition animations, and screen power state. This distinguishes it from the sibling tools like awtrix_notify, awtrix_upsert_app, and awtrix_delete_app.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes the tool's purpose clear enough that an agent can infer when to use it: whenever display-level settings need to be changed. It does not explicitly state when not to use it or name alternatives, but the context is unambiguous given the sibling tool names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

awtrix_test_renderA

Read-onlyIdempotent

Validate and preview a rendered notification/app payload with no hardware side-effects.

ParametersJSON Schema

Name	Required	Default
`hold`	No
`icon`	No
`kind`	No	app
`text`	Yes
`color`	No
`rtttl`	No
`sound`	No
`wakeup`	No
`rainbow`	No
`duration`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already include readOnlyHint=true and idempotentHint=true, lowering the burden on the description. The description adds useful specificity by stating 'no hardware side-effects', clarifying what read-only means in this hardware context. It does not contradict the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single focused sentence with the action front-loaded and the key safety qualifier stated immediately. Every word earns its place; there is no repetition, filler, or structural waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With annotations covering safety, an output schema covering return shape, and schema defaults for optional parameters, the description is just barely viable for a minimal call using only the required `text` parameter. However, it lacks guidance on the notification/app distinction and advanced fields, and relies heavily on the provided schema and the agent's domain inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description provides essentially no parameter-level guidance. It only echoes the 'notification/app payload' concept, which maps to the `kind` enum, but gives no help on ten other parameters, including TextSegment, rtttl, wakeup, rainbow, and color. The description fails to compensate for the missing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action, 'Validate and preview', applied to a defined resource, 'rendered notification/app payload'. It also distinguishes itself from hardware-affecting siblings by explicitly noting 'no hardware side-effects', leaving no ambiguity about what the tool is for.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context that this is a safe preview/validation operation, implying it should be used instead of side-effecting tools like awtrix_notify when testing payloads. It does not explicitly name alternatives or exclusion conditions, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

awtrix_upsert_appA

Idempotent

Create or update a persistent custom app in the display carousel.

ParametersJSON Schema

Name	Required	Description	Default
`icon`	No
`name`	Yes
`save`	No
`text`	Yes
`color`	No
`repeat`	No
`rainbow`	No
`duration`	No
`lifetime`	No
`lifetime_mode`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide idempotentHint and destructiveHint=false, and the description aligns by saying 'create or update' and 'persistent'. It adds useful context about the app living in the display carousel and being persistent, but it does not disclose nuances like the effect of the 'save', 'lifetime', or 'lifetime_mode' parameters on persistence, or whether updating an existing app overwrites prior configuration. No contradiction with annotations exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no wasted words. It is front-loaded with the operation ('Create or update') and immediately clarifies the resource and location ('persistent custom app in the display carousel').

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema (so return values need not be explained), the high parameter count, nested TextSegment definition, and zero parameter descriptions make the overall description insufficient. An agent would not know how to construct a valid 'text' payload, when 'save' should be true, or what lifetime/lifetime_mode mean, so the tool cannot be reliably invoked correctly from the description alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 10 parameters and 0% description coverage, so the description must compensate by explaining parameter meaning. It does not mention a single parameter (name, text, icon, save, color, repeat, rainbow, duration, lifetime, lifetime_mode), leaving the agent to rely solely on schema titles and defaults. This is insufficient for a schema of this complexity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The descrip states a specific verb ('Create or update' — an upsert) and a specific resource ('persistent custom app' in the 'display carousel'). This clearly distinguishes it from siblings such as awtrix_delete_app, awtrix_notify, and awtrix_set_settings because it targets custom app lifecycle management, not deletion, notification, or settings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly conveys when to use this tool: when the goal is to create or update a persistent custom app in the carousel. It does not explicitly name alternatives or state exclusions, but the context is strong enough that an agent can infer the intended use versus notify or delete siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

6 tool updatesv0.1.0Aug 30, 2026
- First observedawtrix_delete_app
- First observedawtrix_get_device_state
- First observedawtrix_notify
- First observedawtrix_set_settings
- First observedawtrix_test_render
- First observedawtrix_upsert_app

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0

Scored 2026-08-30 08:15 across 6 tools

Disambiguation5/5

Each tool targets a distinct operation: app mutation, instant notification, device state query, settings, and safe preview. notify and test_render are clearly separated by side effects, while upsert_app vs notify is distinguished by persistence and priority.

Naming Consistency4/5

All tools share the awtrix_ prefix and use snake_case with a mostly verb_noun pattern. awtrix_notify is a minor outlier because it lacks an explicit object, but the overall naming is still predictable and readable.

Tool Count5/5

Six tools cover a focused display-management scope without redundancy. The count is well within the ideal range, and each tool serves a meaningful purpose.

Completeness4/5

The set covers app create/update/delete, notifications, settings, device state, and safe payload testing. Missing explicit list/get app endpoints are minor gaps that agents can partially work around using the existing app and state tools.

Maintenance

ActivityMaintained

ResponsivenessWithin a week

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

time A
pro.worldclock
A real clock for AI agents: current time, timezone conversion, and DST facts from the IANA tzdb.
Developer Tools
52
agentbay-mcp AOAuth
io.github.thomasjumper
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Knowledge & Memory Autonomous Agents Agent Orchestration
21
zerm A
dev.zerm
Agent utility belt: memory, locks, webhook inboxes, timers, DNS, email, URL, timezone, cron
Knowledge & Memory Agent Orchestration
242
DobbyOAuth
io.github.gil-dobby
Connect, monitor, and control AI agents — tasks, approvals, schedules, and governance.
Agent Orchestration Autonomous Agents Monitoring
2

Related MCP Servers

Home Assistant MCP Server
Home Automation & IoT Agent Orchestration App Automation
Jonathan97480
A
license
Not graded
quality
D
maintenance
Enables AI agents to control and monitor Home Assistant smart home devices through natural language interactions. Supports device control, entity state monitoring, history access, and automation generation with both MCP protocol and standalone HTTP REST API modes.
Updated a year ago (2025-09-22 14:53 UTC)
1
MIT
pixoo-mcp-server
App Automation Home Automation & IoT Multimedia Processing
cyanheads
A
license
A
quality
A
maintenance
Enables programmatic control of Divoom Pixoo LED matrices to display layered pixel art, animations, and hardware-rendered scrolling text. Users can compose complex visual scenes, push images, and manage device settings like brightness and channels through an LLM.
Updated 20 days ago (2026-08-22 21:55 UTC)
7
209
8
Apache 2.0
IoT Device Management MCP
Home Automation & IoT Monitoring
AiAgentKarl
A
license
A
quality
D
maintenance
Enables registration, monitoring, and control of IoT devices via AI agents, with local storage and no cloud API key required.
Updated 5 months ago (2026-04-05 10:06 UTC)
9
MIT
ulanzi-mcp
Home Automation & IoT
Jelloeater
A
license
A
quality
C
maintenance
MCP server and CLI for controlling Ulanzi TC001 Smart Pixel Clock via AWTRIX3 HTTP API. Enables power, brightness, notifications, and more from AI assistants.
Updated 5 months ago (2026-04-13 05:51 UTC)
20
2
MIT

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

Table of Contents

1. Product Requirements Document (PRD)

Problem Statement

Goals & Non-Goals

Goals

Non-Goals

Target Personas & Use Cases

Functional Requirements

Non-Functional Requirements

2. System Architecture & Design

High-Level Architecture

Component Breakdown

3. MCP Tools Specification

awtrix_notify

awtrix_upsert_app

awtrix_delete_app

awtrix_get_device_state

awtrix_set_settings

awtrix_test_render

4. Declarative App Engine (YAML Schema)

Example 1: Service Health (Checkly)

Example 2: Multi-Metric SaaS Dashboard

5. Quickstart & Installation

Prerequisites

Local Setup with uv / pip

Running Tests

Docker & Docker Compose Setup

MCP Client Configuration

1. Google Antigravity

2. Claude Desktop

3. Cursor

6. Roadmap & Contributing

7. License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

`awtrix_notify`

`awtrix_upsert_app`

`awtrix_delete_app`

`awtrix_get_device_state`

`awtrix_set_settings`

`awtrix_test_render`

Local Setup with `uv` / `pip`