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)にいつでも接続し、通知を腕時計にプッシュ、文字盤/クイックアプリのインストール、通知アイコンの管理——スマホとPCが同じ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 核心)

特徴

  • マルチテナント分離:資格情報がテナント。資格情報はスマホAppが生成・保持(AppのLANブリッジトークンを再利用)、サーバーはSHA-256ハッシュのみ保存。異なるテナントのデバイス、ツール、バッファは完全に分離

  • マルチデバイス集約:同じ資格情報で複数のスマホ(iPhone + Android)を接続可能。ツールリストは自動的に重複排除・統合され、呼び出しは最も最近アクティブなデバイスにルーティング

  • オフライン再送:デバイスが10分以内に再接続した場合、直近5分以内の通知系呼び出しを再送(進捗系は最新の1件に自動圧縮、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 里的令牌>"

複数のクライアント(PC、ノートPC、CI)で同じトークンを共有できます。

フェイクデバイスでの連携テスト(スマホ不要)

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

管理

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

レート制限

セキュリティモデル

  • サーバーは資格情報の平文を決して保存しない(SHA-256ハッシュ)。比較は定数時間アルゴリズムを使用

  • 公網デプロイではTLSを強制。トークンは128ビットのエントロピーを持ち、401は送信元IPごとにレート制限

  • 資格情報の失効は即時有効:オンラインデバイスは切断され、MCP側は401、自動復活はしない

  • プライベートモードは「誰がペアリングできるか」をデプロイキー保持者に限定。require_reauth 切り替えで、ペアリング済み全デバイスに再認証を強制可能

LANモードとの関係

LAN直接接続(App内蔵)

リレーサーバー

要件

PCとスマホが同じネットワーク

スマホがインターネットに接続できればよい

アドレス

Wi-Fi変更で変わる

固定

データパス

第三者を経由しない

リレーを経由(サーバーはハッシュと転送された暗号文/呼び出し内容のみ見える)

オフライン

直接失敗

通知系はキューで再送

両方同時に有効にでき、互いに影響しません。

開発

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