Ulanzi MCP Server
MCP server and CLI for the Ulanzi TC001 Smart Pixel Clock (AWTRIX3 firmware).
Features
- MCP Server: Control your Ulanzi clock from AI assistants (Claude Desktop, Cursor, Windsurf)
- CLI Tool: Command-line interface for scripting and automation
- Multi-clock Support: Control multiple clocks from a single instance
- Full API Coverage: Access all AWTRIX3 HTTP API endpoints
Quick Start
1. Install
cd ulanzi-mcp
uv sync
2. Configure
Copy .env.example to .env and set your clock IP:
ULANZI_HOSTS=http://192.168.1.100
For multiple clocks:
ULANZI_HOSTS=http://192.168.1.100,http://192.168.1.101
3. Use CLI
# Check configuration
ulanzi info
# Turn on display
ulanzi power on
# Show notification
ulanzi notify "Meeting in 5 minutes!"
# Set brightness
ulanzi brightness 200
4. Use with MCP (Claude Desktop)
Add to your Claude Desktop config:
{
"mcpServers": {
"ulanzi-mcp": {
"command": "uv",
"args": ["--directory", "/path/to/ulanzi-mcp", "run", "python", "-m", "ulanzi_mcp.server"]
}
}
}
Environment Variables
| Variable | Description | Default |
|---|---|---|
ULANZI_HOSTS |
Clock address(es), comma-separated | http://192.168.1.100 |
ULANZI_USERNAME |
HTTP auth username | (none) |
ULANZI_PASSWORD |
HTTP auth password | (none) |
ULANZI_API_TIMEOUT |
Request timeout (seconds) | 10 |
ULANZI_MQTT_PREFIX |
MQTT topic prefix | awtrix |
Available Tools/Commands
See docs/clock_spec.md for complete documentation.
Development
# Run MCP server in development mode
uv run mcp dev src/ulanzi_mcp/server.py
# Run CLI
ulanzi --help
# Run tests
uv run pytest
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for ulanzi-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| ulanzi_mcp-0.1.0.tar.gz | 78.5 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ulanzi_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 89.5 kB
Release files / ulanzi_mcp-0.1.0.tar.gz
| Download URL | ulanzi_mcp-0.1.0.tar.gz |
|---|---|
| Size | 78.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9917d228bbf01197a994ffb8948c0a748eb541ac9e47cf56735da1a32b648de0
|
|
BLAKE2b-256 checksum How to use checksums |
e1f070878b9a4951f704e0a6f8d150e1a7173d3ff7a6e8befcf9344943c863e4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 18, 2026.
Transparency logRelease files / ulanzi_mcp-0.1.0-py3-none-any.whl
| Download URL | ulanzi_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 11.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
36c68d003d282f38edee9000cae209a84a8d000ff2930aa8d47b21e93bece915
|
|
BLAKE2b-256 checksum How to use checksums |
18a7d10b345534aff448bb2f0fd3f18c5695f21863ce392ba11004e21515640d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 18, 2026.
Transparency logSecurity for ulanzi-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for ulanzi_mcp-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
