Skip to main content
Glama
MobileAiUse

phone-agent-mcp

by MobileAiUse
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

phone-agent-mcp

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

架构概览

外部 AI 客户端（Qoder / OpenClaw / 浏览器端 MCP 客户端）
        │
        │  Streamable HTTP（SSE 流，首选） 或 stdio（JSON-RPC 2.0）
        ▼
┌───────────────────┐      WebSocket       ┌──────────────────────────────┐
│  phone-agent-mcp  │ ◄──────────────────► │  Mobile AI Agent 浏览器页面    │
│  (Node.js 进程)    │    ws://localhost    │  (https://mobile-ai-use.com) │
│                   │      :7788           │                              │
│  ┌──────────────┐ │                      │  ┌─────────────────┐         │
│  │ McpServer    │ │  callBrowser()       │  │ MCP Relay       │         │
│  │ (HTTP+stdio) │ │ ──── tool/args ────► │  │ (WS Client)     │         │
│  │              │ │ ◄─── result ──────── │  │                 │         │
│  │ 9 个 Tools   │ │                      │  │ Agent 调度       │         │
│  │              │ │  progress ◄───────── │  │ 工具执行         │         │
│  └──────────────┘ │                      │  └─────────────────┘         │
└───────────────────┘                      └──────────────────────────────┘

  • MCP 层：基于 @modelcontextprotocol/sdk 的 McpServer，提供两种传输通道：

    • Streamable HTTP（默认 7789 端口，/mcp 端点）：SSE 流式输出结果与中间过程，支持多会话，首选通道

    • stdio：兼容 Qoder / OpenClaw 等本地 CLI 类客户端的传统接入方式

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

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

  • Tasks 扩展：支持 MCP Tasks 扩展（io.modelcontextprotocol/tasks），长耗时任务异步化，客户端可轮询状态、获取进度、断连后恢复

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 (stdio transport)
[phone-agent-mcp] Streamable HTTP on http://localhost:7789/mcp

环境变量

变量名

默认值

说明

PHONE_AGENT_WS_PORT

7788

WebSocket 中继端口号

PHONE_AGENT_HTTP_PORT

7789

Streamable HTTP 端口号

注册的工具（Tools）

工具名

权限

超时

说明

run_agent_task

写入

可配置

在已连接的手机上运行 AI Agent 任务，传入自然语言目标（支持 Tasks 扩展异步执行）

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 实时推送。

MCP Tasks 扩展（异步长耗时任务）

run_agent_task 注册为 task-based 工具（taskSupport: 'optional'），支持 MCP Tasks 扩展（io.modelcontextprotocol/tasks），解决长耗时操作的阻塞与连接中断问题。

工作流程

客户端                                     服务端
  │  tools/call run_agent_task              │
  │  params: { arguments, task: { ttl } }   │
  ├──────────────────────────────────────►│  createTask → 立即返回
  │  CreateTaskResult { task: { taskId,    │  后台继续执行
  │    status: 'working', pollInterval } } │
  │◄──────────────────────────────────────┤
  │  tasks/get { taskId }   ◄── 轮询 ───►  │  notifications/tasks/status 主动推送
  │  … 状态：working（statusMessage=进度）…  │
  │  tasks/result { taskId }                │  任务完成后
  │◄────────────── CallToolResult ─────────┤

任务状态

状态

含义

working

任务执行中，statusMessage 携带最新进度（Agent 思考/步骤）

completed

任务成功完成，可通过 tasks/result 获取最终结果

failed

任务失败（含浏览器未连接、超时等），结果中包含错误信息

cancelled

客户端通过 tasks/cancel 取消

服务端能力声明

"capabilities": {
  "tasks": {
    "list": {},
    "cancel": {},
    "requests": { "tools": { "call": {} } }
  }
}

支持的端点：tasks/get（查状态）、tasks/result（取结果）、tasks/list（列任务）、tasks/cancel（取消）。

关键参数

参数

取值

说明

TTL

timeoutMs + 10min

任务完成后结果保留时长，过期自动清理

pollInterval

2000ms

建议客户端轮询间隔

向后兼容

  • 新客户端（声明 tasks 能力）：带 task 参数调用 → 立即获得 taskId，轮询 tasks/get / 取结果 tasks/result

  • 旧客户端（不带 task 参数）：服务端自动降级为内部轮询，同步等待并直接返回 CallToolResult，行为与旧版一致

注：tasks/cancel 仅标记任务取消并停止结果写入；如需真正中断手机端执行，请另行调用 abort_task 工具。

配置到 AI 客户端

Streamable HTTP（推荐）

支持远程/HTTP 接入的客户端（含浏览器端 MCP 客户端）直接指向 URL：

{
  "mcpServers": {
    "phone-agent": {
      "url": "http://localhost:7789/mcp"
    }
  }
}

验证连通性：

curl -N -X POST http://localhost:7789/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

响应头 mcp-session-id 即会话 ID，后续请求需携带；响应体为 SSE 流（text/event-stream）。

stdio（Qoder / Claude Desktop / OpenClaw 本地接入）

在客户端的 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 客户端中即可看到上述 9 个手机 Agent 工具，直接调用即可操控手机。

Streamable HTTP 传输详解

Streamable HTTP 是 MCP 标准传输协议，服务端通过 SSE 流在同一个 HTTP 响应内依次输出中间过程通知与最终结果，无需客户端额外轮询：

端点

方法

作用

/mcp

POST

客户端消息入口（initialize / tools/call / tasks/* 等），响应为 SSE 流

/mcp

GET

打开独立 SSE 流，接收服务端主动推送（如 notifications/tasks/status）

/mcp

DELETE

关闭会话

流式输出内容

长耗时工具（如 run_agent_task）执行期间，响应流内会实时推送：

  • notifications/progress：Agent 思考/执行进度（客户端声明 progressToken 时）

  • notifications/message：进度日志降级通道

  • notifications/tasks/status：任务状态变更（working/completed/failed）

流末尾为最终 CallToolResult 或 CreateTaskResult（task 模式）。

会话管理

  • 有状态模式：服务端生成 sessionId，随 initialize 响应头 mcp-session-id 下发，后续请求必须携带

  • 每会话一个 McpServer 实例；工具 handler 共享全局浏览器中继与任务存储（taskStore 跨会话，断连重连后可继续轮询任务）

  • CORS 已放开：浏览器端 MCP 客户端可直接访问

连接流程

  1. 启动 mcp-server：pnpm start，启动 stdio / Streamable HTTP 双通道和 WS 中继

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

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

  4. 接入 MCP 客户端：

    • HTTP 客户端指向 http://localhost:7789/mcp（initialize 后携带 mcp-session-id）

    • 本地 CLI 客户端通过 stdio 启动 node dist/server.js

  5. 调用工具：请求经 WS 转发至浏览器执行，结果与中间过程经 SSE / stdio 流式返回

项目结构

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

设计要点

  • 双传输通道：Streamable HTTP（SSE 流式输出结果与中间过程，多会话）与 stdio（本地 CLI 兼容）并存，工具注册逻辑由 createPhoneAgentServer() 工厂函数统一提供

  • 任务存储跨会话共享：InMemoryTaskStore 全局单例，客户端断连重连（新会话）后仍可通过 tasks/get / tasks/result 继续轮询未过期任务

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

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

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

  • 进度双通道：优先使用 notifications/progress（需客户端声明 progressToken），降级为 notifications/message（logging）；task 模式下同步写入 task.statusMessage 并推送 notifications/tasks/status

  • 静默容错：进度推送失败不中断任务执行；任务被取消/TTL 清理后后台写入安全跳过

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

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd
F
license - not found
A
quality
B
maintenance

How are these scores calculated?

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.

Tools

View all tools

Related MCP Servers

  • ADB MCP Server

    LLL-404
    F
    license
    A
    quality
    D
    maintenance
    A MCP server that enables AI assistants to control Android devices via ADB, supporting device info, screen control, input simulation, app management, shell execution, file transfer, and UI parsing.
    20

  • scrcpy-mcp

    JuanCF
    A
    license
    A
    quality
    A
    maintenance
    MCP server that gives AI agents full vision and control over Android devices via ADB and scrcpy. Supports screenshots, input, apps, UI automation, shell, files, and clipboard.
    38
    650
    87
    MIT

  • android-adb-mcp

    qinxiandiqi
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that wraps Android ADB functionality into AI assistant tools, enabling device management, shell execution, file operations, app management, media capture, and log analysis via natural language.
    26
    2
    MIT

View all related MCP servers

Related MCP Connectors

  • microservices.sh

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

  • hithereiamaliff-mcp-nextcloud

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

  • Living Memory

    An MCP memory server. One memory your agents share — across models, devices and apps.

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