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)에 연결하여 알림을 시계에 푸시하고, 워치페이스/퀵 앱을 설치하고, 알림 아이콘을 관리할 수 있게 합니다. 더 이상 휴대폰과 컴퓨터가 같은 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분 동안의 알림 유형 호출을 재전송합니다. (진행률 유형은 자동으로 최신 항목으로 압축되며, 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

관리

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를 강제하세요. 토큰은 128bit 엔트로피를 가지며, 401은 출처 IP별로 레이트 리밋됩니다.

  • 자격 증명 철회는 즉시 적용됩니다. 온라인 장치는 연결이 끊기고, MCP 쪽은 401을 받으며, 자동으로 복구되지 않습니다.

  • 비공개 모드는 '누가 페어링할 수 있는지'를 배포 키를 보유한 사람으로 한정합니다. require_reauth 전환으로 모든 페어링된 장치의 재인증을 강제할 수 있습니다.

LAN 모드와의 관계

LAN 직접 연결(App 내장)

중계 서버

요구 사항

컴퓨터와 휴대폰이 같은 네트워크 대역

휴대폰이 인터넷에 연결만 되면 됨

주소

Wi-Fi를 바꾸면 변함

고정

데이터 경로

제3자를 거치지 않음

중계를 거침(서버는 해시와 전달되는 암호문/호출 내용만 볼 수 있음)

오프라인

즉시 실패

알림 유형은 큐에 넣어 재전송

둘을 동시에 켤 수 있으며 서로 영향을 주지 않습니다.

개발

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