Skip to main content
Glama
MobileAiUse

phone-agent-mcp

by MobileAiUse

phone-agent-mcp

本地 MCP Server — 将 WebADB 浏览器中的 AI Agent 能力暴露为 MCP Tools,供 OpenClaw / Qoder 等外部 AI 客户端通过标准协议调用。

架构概览

外部 AI 客户端(Qoder / OpenClaw)
        │
        │  stdio(JSON-RPC 2.0 / MCP 协议)
        ▼
┌───────────────────┐      WebSocket       ┌──────────────────────────────┐
│  phone-agent-mcp  │ ◄──────────────────► │  Mobile AI Agent 浏览器页面    │
│  (Node.js 进程)    │    ws://localhost    │  (https://mobile-ai-use.com) │
│                   │      :7788           │                              │
│  ┌──────────────┐ │                      │  ┌─────────────────┐         │
│  │ McpServer    │ │  callBrowser()       │  │ MCP Relay       │         │
│  │ (stdio)      │ │ ──── tool/args ────► │  │ (WS Client)     │         │
│  │              │ │ ◄─── result ──────── │  │                 │         │
│  │ 8 个 Tools   │ │                      │  │ Agent 调度       │         │
│  │              │ │  progress ◄───────── │  │ 工具执行         │         │
│  └──────────────┘ │                      │  └─────────────────┘         │
└───────────────────┘                      └──────────────────────────────┘
  • MCP 层:基于 @modelcontextprotocol/sdkMcpServer,通过 StdioServerTransport 与外部客户端通信

  • 中继层:内嵌 ws WebSocket Server(默认 7788 端口),将工具调用请求转发给浏览器页面中的 MCP Relay

  • 进度上报:支持 MCP notifications/progress 协议,Agent 思考/执行过程实时推送至客户端

Related MCP server: scrcpy-mcp

前置条件

  • Node.js ≥ 18

  • pnpm(推荐,项目统一包管理器)

  • Mobile AI Use 浏览器页面已打开并运行(https://mobile-ai-use.com),页面顶栏 MCP Relay 状态指示器绿色亮起即表示已连接

快速开始

# 1. 进入 mcp-server 目录
cd mcp-server

# 2. 安装依赖
pnpm install

# 3. 构建(生成 dist/server.js)
pnpm run build

# 4. 启动服务
pnpm start

开发模式(无需构建,直接运行 TypeScript):

pnpm run dev

启动成功后,控制台输出:

[phone-agent-mcp] WebSocket relay on ws://localhost:7788
[phone-agent-mcp] MCP server ready (McpServer, stdio transport)

环境变量

变量名

默认值

说明

PHONE_AGENT_WS_PORT

7788

WebSocket 中继端口号

注册的工具(Tools)

工具名

权限

超时

说明

run_agent_task

写入

可配置

在已连接的手机上运行 AI Agent 任务,传入自然语言目标

abort_task

写入

10s

中止当前正在运行的 Agent 任务

get_task_result

只读

10s

按任务 ID 获取已完成任务的详细结果(含步骤)

get_latest_task

只读

10s

获取当前对话中最近一次 Agent 任务的结果

take_screenshot

只读

30s

对已连接的手机屏幕截图,返回 PNG 图片

get_device_status

只读

15s

获取设备信息(型号、品牌、系统版本等)

search_memory

只读

10s

按关键词搜索 Agent 的持久化记忆库

save_memory

写入

10s

保存一条语义记忆到记忆库

delete_memory

写入

10s

按 ID 删除一条记忆

run_agent_task 详解

参数

类型

必填

说明

goal

string

自然语言任务目标,如 "打开微信,向张三发送你好"

timeoutMs

number

最大执行时间(毫秒),默认 1,200,000(20 分钟)

Agent 将自动规划执行步骤,通过屏幕视觉识别和触摸控制完成目标。执行期间的思考/工具调用/步骤结果会通过 MCP notifications/progress 实时推送。

配置到 AI 客户端

Qoder / Claude Desktop

在客户端的 MCP 配置文件中添加:

{
  "mcpServers": {
    "phone-agent": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/server.js"],
      "env": {
        "PHONE_AGENT_WS_PORT": "7788"
      }
    }
  }
}

OpenClaw

mcp_servers:
  phone-agent:
    command: node
    args:
      - /path/to/mcp-server/dist/server.js
    env:
      PHONE_AGENT_WS_PORT: "7788"

配置完成后,AI 客户端中即可看到上述 8 个手机 Agent 工具,直接调用即可操控手机。

连接流程

  1. 启动 mcp-serverpnpm start,启动 stdio MCP 服务和 WS 中继

  2. 打开浏览器页面:访问 WebADB 页面,确保设备已连接

  3. 确认 Relay 连接:页面顶栏 Relay 状态指示器变绿,控制台输出 Browser connected

  4. 调用工具:外部 AI 客户端通过 MCP 调用工具,请求经 WS 转发至浏览器执行,结果原路返回

项目结构

mcp-server/
├── src/
│   └── server.ts          # 主服务:McpServer + WS + 8 个工具注册
├── dist/
│   └── server.js          # 编译产物
├── package.json
├── tsconfig.json           # TypeScript 配置(ES2022 / NodeNext)
└── pnpm-lock.yaml

技术栈

组件

版本

用途

@modelcontextprotocol/sdk

^1.12.0

MCP 服务端框架(McpServer + StdioServerTransport)

ws

^8.18.0

WebSocket 服务端,中继浏览器连接

zod

^4.4.3

工具参数校验与 Schema 声明

typescript

~5.8.3

类型安全

tsx

^4.19.0

开发模式直接运行 TS

设计要点

  • 单浏览器连接:同一时刻只接受一个浏览器 WS 连接,新连接替换旧连接

  • 请求-响应匹配:通过 id 字段将 WS 响应路由到对应的挂起 Promise

  • 超时兜底:每个工具调用有独立超时,超时返回错误信息而非挂死

  • 进度双通道:优先使用 notifications/progress(需客户端声明 progressToken),降级为 notifications/message(logging)

  • 静默容错:进度推送失败不中断任务执行

  • 浏览器离线提示:WS 未连接时返回友好错误 "Browser not connected"

Install Server
F
license - not found
A
quality
C
maintenance

Maintenance

Maintainers
Response time
Release cycle
Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.

  • A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…

  • MCP server exposing the Backtest360 engine API as tools for AI agents.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/MobileAiUse/mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server