Skip to main content
Glama
PeterTianbuhan

phone-mcp

by PeterTianbuhan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Hybrid

Phone Agent Runtime

把一台 Android 手机（首台：荣耀 Magic7）变成已有 Agent 的长期行动端：手机上一个 APK 负责可靠执行、本地策略与随时暂停；电脑上一个进程负责配对、连接和把手机能力以 MCP 工具 暴露给任何 Agent（Claude Code、Codex 等）。

设计合同见 docs/design/，连接拓扑（局域网 / VPS 中转 / VPS 全部署）见 docs/design/CONNECTION.md，评估与决策见 docs/adr/，机器可校验的协议见 protocol/。手机端体验原型见 docs/prototype/。许可证：MIT（见 LICENSE）；第三方声明见 NOTICE。

仓库结构

apps/
  android/            Kotlin：:runtime（纯 JVM 可靠性内核 + FakeBackend + 验收测试）、:app（APK）
  control/server/     TypeScript：Gateway(WSS) + Device Tools + MCP server + CLI + node:sqlite 任务库
protocol/             协议 v1：JSON Schema、示例、契约测试（两端实现以此为准）
docs/
  design/             来自 ChatGPT 讨论的设计包（ARCHITECTURE / PROTOCOL / CODEX_HANDOFF / 图）
  adr/                架构决策记录
  acceptance-results.md   A01–A20 验收结果与证据（真机项逐条注明）

Related MCP server: android-phone-mcp-server

快速开始

# 协议契约测试
pnpm install
pnpm --filter @phone-runtime/protocol validate

# 手机端可靠性内核测试（无需手机）
cd apps/android && export JAVA_HOME=/opt/homebrew/opt/openjdk@17 && ./gradlew :runtime:test

# 控制端
pnpm --filter @phone-runtime/control build && pnpm --filter @phone-runtime/control test

各子目录的 README 有完整的运行、配对与接入 Claude Code / Codex 的步骤。

不可改变的边界（摘自设计包）

  • 手机执行，Agent 规划；控制端只做配对、认证、路由与协议翻译，不含第二套绕过手机内核的执行逻辑。

  • 手机本地暂停与撤权不依赖网络；前台 UI 同时只有一个控制会话。

  • 动作日志是手机的权威事实：同 action_id 去重、不同 payload 冲突、派发前落盘 EXECUTING、结果与 Outbox 同事务、崩溃后 UNCERTAIN 而非重做。网络超时不等于未执行。

  • 手机不开任何控制端口；只主动出站 WSS。release 无调试入口。

  • 页面文字、聊天消息、无障碍读到的内容都不能成为授权。

状态

见 docs/acceptance-results.md。真机相关项在 Magic7 接入前一律标记为未验证。

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

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • android-phone-mcp-server

    expoli
    A
    license
    A
    quality
    A
    maintenance
    MCP server for controlling Android devices via semantic actions with verification, enabling any MCP client to interact with phones through natural language and structured tools.
    18
    2
    MIT

  • ThumbAgent

    LiuShiYi1027
    A
    license
    Not graded
    quality
    A
    maintenance
    Local-first MCP server that enables AI agents to safely control and observe Android mobile devices, supporting device diagnostics, app lifecycle management, async task execution, and performance monitoring through a policy-constrained interface with explicit confirmations.
    Apache 2.0

  • phone-harness

    ZachDreamZ
    A
    license
    Not graded
    quality
    A
    maintenance
    Controls Android and iOS devices from AI agents through a token-efficient MCP server, enabling observation, tapping, typing, gestures, navigation, assertions, and safety-gated actions.
    MIT