AzkiDeck-mcp-server

AzkiDeck's multi-tenant MCP relay server: lets MCP clients (Claude Desktop / Claude Code, etc.) connect to the AzkiDeck App (Android / iOS) on the user's phone from anywhere, push notifications to the watch, install watch faces/quick apps, manage notification icons — no longer requiring the phone and computer to be on the same LAN.

MCP 客户端(Claude Desktop 等)
        │  POST /mcp  (Streamable HTTP, 无状态, Bearer 令牌)
        ▼
┌─────────────────────────────────────────────┐
│            azkideck-mcp-server              │
│  node:http ─┬─ /mcp      → MCP 分发          │
│             ├─ /device   → 设备接入(WS)      │
│             ├─ /admin/*  → 管理面            │
│             └─ /healthz                     │
│  多租户:凭证即租户,SHA-256 哈希隔离         │
│  持久化:SQLite(node:sqlite,零原生依赖)     │
└─────────────────────────────────────────────┘
        ▲  wss://server/device (手机出站连接,绕开 NAT)
        │  register → mcp-request/response ↔ replay
   Android / iOS App(复用 App 内已有的 MCP 核心)

Features

• Multi-tenant isolation: credentials are tenants. Credentials are generated and held by the phone App (reusing the App's LAN bridge token); the server only stores SHA-256 hashes; devices, tools, and buffers of different tenants are completely isolated

• Multi-device aggregation: the same credential can be attached to multiple phones (iPhone + Android); tool lists are automatically deduplicated and merged, and calls are routed to the most recently active device

• Offline replay: if a device reconnects within 10 minutes of disconnection, notification-type calls from the last 5 minutes are replayed (progress-type calls are automatically compacted to the latest one; cleared notifications are not replayed); if the window is exceeded, the device is considered offline and no replay occurs

• Public/private dual mode: in public mode, pairing only requires entering the address; private mode additionally requires a deployment key; can be switched at runtime, and when switching you can choose whether to require already-paired devices to re-authenticate

• Minimal dependencies: only one runtime dependency, ws; Node ≥ 22.13 (uses built-in node:sqlite)

Related MCP server: Remote Control MCP (Electrobun)

Quick Start

# 需要 Node.js ≥ 22.13。尚未发布到 npm registry,从源码安装:
git clone https://github.com/AzumaChiaki/AzkiDeck-mcp-server.git
cd AzkiDeck-mcp-server
npm ci && npm run build

node dist/cli.js serve     # 默认监听 0.0.0.0:8787
# 可选:npm link 注册全局 azkideck-mcp-server 命令

Public deployments must enable TLS (built-in TLS_CERT/TLS_KEY, or use Caddy/nginx reverse proxy); see docs/deployment.md.

Phone Configuration

1. App → Toolbox → AI Notification Bridge: make sure it is enabled (the token is here)

2. Relay mode (settings page): enter the server address; the credential automatically reuses the bridge token; if the server is in private mode, you also need to enter the deployment key

3. Pairing is complete when the App shows "Relay Connected"

MCP Client Integration

claude mcp add --scope user --transport http azki-watch \
  https://你的服务器/mcp --header "Authorization: Bearer <手机 App 里的令牌>"

Multiple clients (desktop, laptop, CI) can share the same token.

Fake Device Debugging (No Phone Required)

azkideck-mcp-server serve &
node scripts/fake-device.mjs --server ws://127.0.0.1:8787 --credential <任意32位hex>
# 之后 Claude 里调用 send_notification,假设备终端会打印 payload

Administration

azkideck-mcp-server tenants list                    # 租户列表
azkideck-mcp-server tenants create                  # 预置租户(AUTO_REGISTER=false 时)
azkideck-mcp-server tenants revoke <id前缀>         # 撤销
azkideck-mcp-server tenants allow <id前缀>          # 恢复
azkideck-mcp-server mode get                        # 查看公开/私有模式
azkideck-mcp-server mode set private --key <hex> [--reauth]

Runtime management API (enabled by the ADMIN_TOKEN environment variable):

Configuration (Environment Variables)

Security Model

• The server never stores credentials in plaintext (SHA-256 hash); comparison uses a constant-time algorithm

• Enforce TLS for public deployments; tokens have 128 bits of entropy, 401s are rate-limited by source IP

• Credential revocation takes effect immediately: online devices are kicked, MCP side gets 401, and there is no automatic recovery

• Private mode restricts "who can pair" to holders of the deployment key; toggling require_reauth can force all paired devices to re-authenticate

Relationship with LAN Mode

Both can be enabled simultaneously without affecting each other.

Development

npm install
npm run dev        # tsx watch
npm test           # vitest(含 e2e:真实端口 + 假设备)
npm run lint && npm run typecheck

See docs/protocol.md for protocol details (phone-side implementation specification).

License

Apache-2.0