MCP Server Awtrix（mcp-server-awtrix）是一个开源的 Model Context Protocol (MCP) 服务器和声明式指标编排器，旨在让 AI 代理（Antigravity、Claude Desktop、Cursor、Cline、AutoGPT 等）完全控制运行 Awtrix Light 的 Ulanzi TC001 及兼容像素矩阵智能时钟。
它桥接了对话式和自主式 AI 代理与物理桌面显示器，支持：
即时代理警报：将临时状态警报、构建失败通知和任务完成推送到像素屏幕。
动态轮播应用：注册、更新和循环自定义实时遥测应用（服务器健康、SaaS 指标、收入计数器、构建状态）。
声明式指标轮询器：通过 YAML 规范自动化后台 API 获取和阈值格式化，无需编写自定义 Python 脚本。
硬件遥测与控制：检查电池电量、调整矩阵亮度、管理电源状态，并触发自定义声音提示。
Related MCP server: pixoo-mcp-server
运行智能像素时钟（如带 Awtrix Light 的 Ulanzi TC001）的开发者和高级用户目前需要编写零散的、硬编码的 Python 或 Bash cron 脚本来查询外部 API 并更新矩阵应用。
当与 AI 编码代理协作时：
代理必须为每个指标生成并维护原始的命令式代码。
没有标准化的工具集供 AI 代理发送实时通知或管理显示生命周期。
密钥管理容易出错，存在 API 密钥在 AI 提示和日志中泄露的风险。
对于多段文本格式和像素图标，没有原生的回退或验证机制。
原生 MCP 接口：提供一个标准的 Model Context Protocol 服务器，暴露用于通知、自定义应用、设备管理和预览的健壮工具。
声明式遥测：让代理和人类能够在简单的 YAML 文件中定义指标轮询规则，并内置模板（Jinja2）和阈值样式。
安全密钥隔离：通过 .env 环境变量替换，将敏感凭据与提示上下文解耦。
零停机热重载：无需重启服务即可自动反映 YAML 配置文件中的更改。
可靠回退：优雅处理网络中断、API 速率限制和离线显示状态。
替换 Awtrix Light 固件（此工具仅与官方 Awtrix Light REST/MQTT API 交互）。
复杂的多显示器平铺同步（重点是单实例或多实例独立像素时钟）。
用户角色 | 场景 | MCP Server Awtrix 如何帮助 |
AI 编码代理（例如 Antigravity / Cursor） | 代理在后台完成 10 分钟的测试套件或自主任务。 | 调用 |
DevOps / SRE 工程师 | 想要监控生产可用性、错误预算或 Checkly 合成测试。 | 放置 |
SaaS 创始人 / 构建者 | 想要在桌面上循环显示实时 MRR、新用户注册和支持工单计数器。 | 定义查询后端管理端点的声明式多指标应用。 |
FR-1：即时通知 (/api/notify)：
支持自定义文本、多段彩色文本、图标 ID、声音/RTTTL 铃声、优先级保持和持续时间。
FR-2：自定义轮播应用 (/api/custom)：
能够注册、更新和从显示循环中移除命名应用。
支持富文本段格式（[{"t": "FAIL", "c": "FF0000"}, {"t": " (2/10)", "c": "FFFFFF"}]）。
FR-3：声明式后台引擎：
内置调度器（asyncio / apscheduler）执行在 apps/*.yaml 中定义的轮询任务。
支持计算变量、算术和条件表达式的模板引擎。
FR-4：设备状态与遥测：
查询电池百分比、Wi-Fi RSSI、光照传感器、矩阵状态和活动应用。
调整亮度、睡眠/唤醒状态和过渡效果。
FR-5：试运行与模拟：
预览工具，在提交到硬件之前返回精确的渲染 JSON 负载和颜色验证。
延迟：直接 MCP 工具执行必须在本地网络上 $< 150\text{ms}$ 内分发到 Awtrix。
弹性：编排器在将应用标记为降级之前，使用指数退避重试失败的 API 获取。
可移植性：打包为标准 Python 包，支持 uv/pipx、Docker 容器和独立 CLI。
┌──────────────────────────┐
│ 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)│
└──────────────────────────┘MCP 接口层：
通过 stdio 和 SSE 实现 Model Context Protocol 服务器端点。
为 AI 模型暴露具有严格 JSON 模式和人类可读文档的工具。
声明式轮询引擎：
管理基于文件的应用清单的任务生命周期的异步工作器。
评估 HTTP 请求，使用 JSONPath/表达式提取字段，并解析显示规则。
Awtrix 驱动：
封装设备通信、请求去重、连接池和错误恢复。
配置与安全层：
将敏感令牌隔离到 .env 中。配置文件通过 ${VAR_NAME} 语法引用变量。
AI 代理可以执行以下 MCP 工具：
awtrix_notify向屏幕推送即时、高优先级的通知（中断当前轮播）。
{
"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在轮播循环中注册或更新持久自定义应用。
{
"name": "app_users",
"text": [
{"t": "1,420", "c": "FFFFFF"},
{"t": " (+42)", "c": "00FF00"}
],
"icon": "2058",
"duration": 5,
"lifetime": 300
}awtrix_delete_app从设备循环中移除自定义应用。
{
"name": "app_users"
}awtrix_get_device_state返回硬件统计数据和当前运行指标。
响应：
{
"online": true,
"battery": 88,
"charging": true,
"lux": 140,
"temp": 24,
"ram_free": 128440,
"active_app": "app_users",
"brightness": 120
}awtrix_set_settings配置设备参数，如亮度、矩阵开关和过渡速度。
{
"brightness": 80,
"power": true
}awtrix_test_render试运行辅助工具，解析表达式并返回渲染负载，而不推送到硬件。
无需维护自定义 Python 脚本，将 .yaml 清单放在 apps/ 目录中。
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" }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" }Python 3.10 或更高版本
已刷入 Awtrix Light 固件 的 Ulanzi TC001（或兼容设备），并连接到您的 Wi-Fi 网络。
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在本地通过 stdio 运行 MCP 服务器：
# Using uv (recommended)
uv run mcp-server-awtrix
# Or standard pip
pip install -e .
python -m awtrix_mcp使用 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_servers.json：
{
"mcpServers": {
"awtrix": {
"command": "uv",
"args": ["--directory", "/path/to/mcp-server-awtrix", "run", "mcp-server-awtrix"],
"env": {
"AWTRIX_BASE_URL": "http://awtrix3.local"
}
}
}
}添加到 claude_desktop_config.json：
{
"mcpServers": {
"awtrix": {
"command": "python",
"args": ["-m", "awtrix_mcp"],
"env": {
"AWTRIX_BASE_URL": "http://awtrix3.local"
}
}
}
}在 Cursor 设置 $\rightarrow$ 功能 $\rightarrow$ MCP 服务器 $\rightarrow$ 添加服务器：
名称：awtrix
类型：command
命令：uv --directory /path/to/mcp-server-awtrix run mcp-server-awtrix
核心 MCP 工具规范与设计
声明式 YAML 编排模式
使用异步 HTTP 客户端的 FastMCP 实现
矩阵像素艺术的实时视觉 Web 预览
MQTT 传输层支持（REST 的可选替代方案）
Home Assistant 服务发现导出
欢迎贡献！请提交 PR 或打开 issue 进行功能讨论。
根据 MIT 许可证 分发。有关更多信息，请参阅 LICENSE。
This server cannot be installed
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
A real clock for AI agents: current time, timezone conversion, and DST facts from the IANA tzdb.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Wall-clock awareness for LLM agents. Two tools: elapsed-time-between-turns + day rollover detection.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/klodnickik/mcp-server-awtrix'
If you have feedback or need assistance with the MCP directory API, please join our Discord server