Skip to main content
Glama
deenesjakoruzh
AzumaChiaki

AzkiDeck-mcp-server

by AzumaChiaki
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

AzkiDeck-mcp-server

AzkiDeck 的多租户 MCP 中继服务器:让 MCP 客户端(Claude Desktop / Claude Code 等)随时随地连到用户手机上的 AzkiDeck App(Android / iOS),把通知推上手表、安装表盘/快应用、管理通知图标——不再要求手机与电脑处于同一局域网。

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 核心)

特性

  • 多租户隔离:凭证即租户。凭证由手机 App 生成并持有(复用 App 的局域网桥接令牌),服务器只存 SHA-256 哈希;不同租户的设备、工具、缓冲完全隔离

  • 多设备聚合:同一凭证可挂多台手机(iPhone + 安卓),工具列表自动去重合并,调用路由到最近活跃的设备

  • 离线补发:设备断连 10 分钟内重连,补发最近 5 分钟内的通知类调用(进度类自动压实为最新一条,被 clear 的通知不再补);超窗判离线不补发

  • 公开/私有双模式:公开模式填地址即可配对;私有模式还需部署密钥;运行中可切换,切换时可选择是否要求已配对设备重新认证

  • 极简依赖:运行时仅 ws 一个依赖;Node ≥ 22.13(使用内置 node:sqlite)

Related MCP server: AItomation MCP relay

快速开始

# 需要 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 命令

公网部署必须启用 TLS(内置 TLS_CERT/TLS_KEY,或用 Caddy/nginx 反代),详见 docs/deployment.md。

手机端配置

  1. App → 工具箱 → AI 通知桥接:确认已开启(令牌即在这里)

  2. 中继模式(设置页):填入服务器地址,凭证自动复用桥接令牌;服务器为私有模式时还需填部署密钥

  3. App 显示「中继已连接」即完成配对

MCP 客户端接入

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

多个客户端(电脑、笔记本、CI)可共享同一令牌。

假设备联调(无需手机)

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

远程安装大文件(表盘/快应用)

MCP 工具参数是 JSON,大文件走 base64 会撞报文上限。远程安装用「文件投递 + url 模式」:

# 1. 把文件投到中继(30 分钟有效,仅持同一令牌者可取)
curl -X POST https://你的服务器/files \
  -H "Authorization: Bearer <令牌>" --data-binary @表盘.face
# → {"url":"https://你的服务器/files/<id>","size":…,"sha256":"…","expires_at":…}

# 2. 让 Claude 调用 install_resource,url 填上一步返回的地址
#    手机 App 会自己从该 URL 下载并装到手表

管理

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]

运行时管理 API(ADMIN_TOKEN 环境变量启用):

端点

说明

GET /healthz

公开健康检查,含软件版本及计数

GET /admin/tenants

租户列表(id 仅显示 8 位前缀)

GET /admin/tenants/:id/devices

在线设备

POST /admin/tenants/:id/revoke / allow

撤销/恢复

GET /admin/mode / POST /admin/mode

查看/切换模式;{"mode":"private","deployment_key":"<hex>","require_reauth":true}

配置(环境变量)

变量

默认

说明

PORT / HOST

8787 / 0.0.0.0

监听地址

DATA_DIR

./data

SQLite 数据目录

AUTO_REGISTER

true

公开模式下设备首连自动建租户

ADMIN_TOKEN

(无)

设置后启用 /admin/*

TLS_CERT / TLS_KEY

(无)

都设置则启用内置 HTTPS/WSS

CALL_TIMEOUT_MS / INSTALL_TIMEOUT_MS

30000 / 60000

工具调用超时

BUFFER_TTL_MS

300000

离线缓冲保留 5 分钟

RECONNECT_WINDOW_MS

600000

断连补发窗口 10 分钟

RATE_MCP_PER_MINUTE / RATE_WS_PER_MINUTE / RATE_AUTH_FAIL_PER_MINUTE

120 / 600 / 20

限流

FILE_MAX_BYTES / FILE_TTL_MS

64MiB / 1800000

文件投递上限与保留时长

安全模型

  • 认证存储只保存凭证的 SHA-256 哈希,比较使用常量时间算法;中继终止 TLS,运行时会接触认证令牌和调用内容,上传文件以明文临时存储,应保护数据目录

  • 公网部署请强制 TLS;令牌有 128bit 熵,401 按来源 IP 限流

  • 撤销凭证立即生效:在线设备被踢、MCP 侧 401、且不会自动复活

  • 私有模式把「谁能配对」收敛到持有部署密钥的人;require_reauth 切换可强制全部已配对设备重新认证

工具的四项 MCP annotations、逐工具判定依据和旧设备兼容策略见 docs/tool-annotations.md。这些是行为提示,不是权限控制或安全认证。

与局域网模式的关系

局域网直连(App 内置)

中继服务器

要求

电脑手机同网段

手机能上网即可

地址

换 Wi-Fi 会变

固定

数据路径

不经过第三方

经过中继(TLS 分段加密,中继可见令牌与调用/响应明文;不提供端到端加密)

离线

直接失败

通知类排队补发

两者可同时开启,互不影响。

开发

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

协议细节见 docs/protocol.md(手机端实现规范)。

License

Apache-2.0

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • remote-desktop-commander by desktop-commander

    remote-desktop-commanderofficial

    desktop-commander
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables secure remote access to your computer's filesystem and terminal through MCP, allowing AI assistants to manage files, run commands, and automate tasks from anywhere via a hosted relay.
    145
    -

  • phone-mcp

    PeterTianbuhan
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables desktop agents such as Claude Code and Codex to control an Android phone as a long-lived action endpoint, pairing over outbound WebSocket and exposing phone capabilities as MCP tools with local pause and revocation.
    MIT

  • porchlight

    mahali00
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables remote MCP clients to access local MCP servers and command-line tools over the web, with user approval required for every connection.
    1
    MIT