mctlhq/mctl-alice

Model Context Protocol (MCP) server for controlling Yandex Station (Алиса) smart speakers and smart home devices through the official Yandex Smart Home API and, optionally, the unofficial Quasar API.
Enables AI assistants (Claude, ChatGPT, Codex, Antigravity, OpenClaw, Cursor, etc.) to speak through your Alice speakers, send voice commands, control volume and playback, and manage your smart home.
## Deployment Modes
### 1. Hosted Multi-Tenant SaaS (Recommended)
You can connect your AI assistant directly to our hosted cloud gateway at https://alice.mctl.ai:
1. Open https://alice.mctl.ai in your browser.
2. Click Войти через Яндекс ID to authenticate your Yandex Smart Home.
3. Configure Quasar Cookie (via QR code) if you wish to control smart speakers with TTS phrases.
4. Add the MCP endpoint to your client:
Claude Desktop / Codex / ChatGPT MCP: https://alice.mctl.ai/mcp
Complete the standard OAuth 2.1 consent screen in your client.
### 2. Self-Hosted (Docker)
You can deploy your own instance of mctl-alice using Docker:
bash
docker run -d \
--name mctl-alice \
-p 8080:8080 \
-v $(pwd)/data:/app/data \
-e AUTHREQUIRED=true \
-e PUBLICBASEURL=https://your-domain.com \
-e ENCRYPTIONKEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef \
-e YANDEXCLIENTID=youryandexclientid \
-e YANDEXCLIENTSECRET=youryandexclientsecret \
ghcr.io/mctlhq/mctl-alice: # e.g. 2.2.7, see Releases
Set PUBLICBASEURL to the exact origin browsers use to reach the server. With AUTHREQUIRED=true, the account pages, the consent form and the credential forms accept a POST only from that origin. Without auth, they and browser requests to /mcp and /api/ are accepted only from that origin or from a loopback host (localhost, 127.0.0.1, [::1]). Pages still load from any name, but a server reached as http://nas.local:3000 without a matching PUBLICBASEURL rejects its own forms and requests with 403.
### Request limits
Bodies are capped at 64 KiB (forms) and 1 MiB (MCP/REST JSON, MAXMCPBODYBYTES), and OAuth, sign-in and MCP routes are rate limited per client (RATELIMITREGISTER|TOKEN|AUTHORIZE|LOGIN|QR|QRSTATUS|ACCOUNT|MCP, requests per minute). Behind a reverse proxy set CLIENTIPHEADER to a header the proxy overwrites with the client address (cf-connecting-ip behind Cloudflare), or TRUSTPROXYHOPS to the number of trusted proxies so the address is taken from X-Forwarded-For; set either only behind a proxy you control, since otherwise clients can spoof their rate-limit key. See SECURITY.md for the defaults.
### Telemetry retention
Telemetry samples older than TELEMETRYRETENTIONDAYS (default 30) are deleted in every mode, whether or not this instance samples: one minute after start and then every 6 hours, in batches of 5,000 rows. Each run logs one line with the number of rows deleted and the duration.
### Metrics
Set METRICSPORT (for example 9464) to serve Prometheus metrics at GET /metrics on a separate listener; unset, no metrics are served. The application port never answers /metrics. The metrics listener binds all interfaces and has no authentication, so expose only the application port through your proxy and firewall the metrics port (on a host-network or plain Docker install, do not publish it). A metrics port that cannot be bound is logged and leaves the application running without metrics. Metrics: mctlalicehttprequeststotal (route template, method, status class), mctlaliceauthfailurestotal (reason), mctlaliceratelimitedtotal (bucket), mctlaliceupstreamrequeststotal and mctlaliceupstreamrequestdurationseconds (Yandex upstream and outcome), and mctlalicebuildinfo. Label values come from fixed sets; no path, query string or token reaches a label.