近一年我在做移动端 AI 应用时几乎天天跟 Model Context ProtocolMCP打交道。这个协议把大模型和外部工具之间的连接方式标准化现在你去看各个大模型客户端的插件市场清一色都在走 MCP。但当我把这套东西搬到手机上发现完全不是官网文档里写的那样简单。标题里的 mobile-mcp 就是我这一年折腾下来的总结手机上的 MCP 到底该怎么设计、怎么实现、怎么排查问题。先说结论mobile-mcp 不是一个单一的开源包而是一整套移动端接入 MCP 的实践方法。手机既可以当 AI 的客户端去连远程的 MCP 服务也可以自己当服务端把通讯录、定位、传感器、通知这些设备能力暴露给 AI。这个方向解决的核心问题是大模型拿不到你的真实场景数据——你在电脑上让 AI 帮你查个日历很容易在手机上它连你当前在哪、手机还剩多少电都不知道。写这篇文章是想给做移动 AI 应用、做自动化测试、或者打算在手机端跑本地模型的人一条可以抄的路线顺便把那几个我反复踩坑的地方提前跟你说清楚。1. 先说清楚mobile-mcp 到底在解决什么问题1.1 MCP 协议快速回顾MCP 是 Anomaly 体系带起来的一个开放协议它定义了一套 AI 应用叫 Host和工具服务叫 Server之间的通信规则。你可以把它理解成给 AI 装 USB-C 口以前每接一个新工具都要单独给 AI 写一段适配代码有了 MCP 之后只要工具方实现了 Server任何支持 MCP 的客户端都能直接调用。这套协议的消息格式是 JSON-RPC 2.0核心就三个概念Tools工具模型可以主动调用的函数、Resources资源可以读给模型的数据、Prompts提示模板。Host 和 Server 之间走传输层官方定义过 stdio、HTTPSSE、WebSocket后来又推出了 Streamable HTTP 作为统一推荐。我在桌面端做得挺顺一个 Python 脚本配上 FastMCP 就能把本地文件、数据库全部暴露给 Claude Desktop。但产品要往移动端走的时候问题就冒出来了手机上没有 Python 环境iOS 的 App 沙箱管得死死的Android 的后台进程说杀就杀蜂窝网络和 Wi-Fi 切换时连接秒断。这些在服务器上根本不存在的问题移动端全都要重新设计一遍。1.2 移动端引入 MCP 的三个典型场景我梳理下来现实中 mobile-mcp 主要出现在三类需求里。第一类是手机 App 内嵌 AI 助手需要读取 App 自身的数据。比如一个记账 App 想让用户用自然语言问我这个月餐饮花了多少传统做法是在代码里写死查询逻辑。有了 MCP记账户直接把内部的数据查询封装成工具让大模型自己决定怎么调用。这里的价值是标准化今天接 GPT明天换通义千问工具的暴露方式不用改换 Host 就行。第二类是手机设备本身成为 AI 的操作对象。典型例子是自动化测试和手机控制。电脑上的 MCP Server 通过 ADB 或苹果的测试通道桥接到手机AI 可以看屏幕截图、模拟点击、读取界面元素相当于把整个手机变成一个可以被模型操作的真机沙盒。我在做 App 回归测试时这么干过比写 UIAutomator 脚本高效太多——让模型自己理解界面状态并生成操作序列用例维护量直线下降。第三类是端侧 AI 场景手机上跑本地小模型模型要获取传感器、位置、电池这些实时能力靠的就是手机内部或者近场的一个 MCP Server 把这些能力以工具形式暴露出来。这个方向对隐私敏感的产品尤其有吸引力数据不出设备模型在本机推理工具在本机调用。这三类场景覆盖了 MCP 的三种角色分配手机当客户端、电脑当桥接端、手机当服务端。它们的技术难点各不相同后面我分开细说。1.3 与桌面/服务端 MCP 的差异点很多人照着桌面端的经验做移动端上来就翻车。我列一下本质差异你感受下为什么不能直接照搬。首先是运行时环境。桌面端 MCP Server 通常是一个独立进程有完整的语言运行时和文件系统权限。手机端不行App 被沙箱隔离你不能随随便便开一个监听端口的进程iOS 上你连绑定一个 TCP 端口这个操作都做不了除非走网络扩展框架。所以移动端 Server 的宿主要么是一个内嵌的本地库要么通过 WebView 和服务端中转。其次是生命周期。桌面端进程一直在连接断了重连就行。手机 App 一进后台就可能被系统挂起iOS 的 suspend 机制、Android 的 Doze 模式都会直接掐断网络。你设计的 MCP Server 必须感知 App 前后台切换在合适的时机挂起和恢复。然后是权限模型。服务端的 MCP Server 通常信任调用方反正都在自己的机房里。手机上的 MCP Server 暴露的是真实用户数据通讯录、相册、定位任何一个工具被滥用都是安全事故。桌面端你不需要考虑这个工具能不能读用户的通讯录移动端你必须设计清楚每一层授权。最后是网络特征。手机的 IP 会变Wi-Fi 和蜂窝网络切换时 TCP 连接直接失效。如果你在手机上只实现了 WebSocket 长连接而没有重连和断点续传用户切个网你的整个 AI 调用链就断了。这些坑我在第 5 节详细展开。2. 架构选型四种移动端落地形态2.1 手机当客户端最简单但最受限的形态这是最轻的一种手机上的 App 只作为 MCP Host 和 Client所有的 MCP Server 都跑在远端。你的 App 通过 HTTP 连接你自己的服务器服务器上跑着各种 MCP 工具AI 模型也在云端。这种形态下移动端几乎不用做什么额外工作SDK 都是现成的。只要处理好几件事就行网络切换时的请求重试、弱网下的超时设置、以及保证用户在蜂窝网络下不会因为流量费用突然拉起一堆大模型请求。但它的局限恰恰在于手机只是个窗口。App 拿不到本地设备数据除非你把数据上报到云端再喂给模型那就引出了隐私问题。所以这种形态适合工具类 MCP 服务比如连天气、连搜索、连企业内部系统不适合做个人智能助理——一个连你手机上有哪些通知都不知道的助手谈不上个人。2.2 手机当服务端端内跑一个轻量 MCP Server这是 mobile-mcp 最有想象空间、也最难做的形态。你的手机在自己的进程里跑一个 MCP Server把这个设备上的能力以 Tools 的形式暴露出去。端点可以是 localhost 上的某个端口也可以只对本机 App 内部开放本质上是一个设备能力抽象层。我自己的实践是在 Android 上用 Termux 跑 Node.js 写了一个小 Server把电池、定位、Wi-Fi 状态暴露成一个本地 HTTP 端口然后用电脑上的大模型通过局域网去访问。这个手机即数据库、电脑即大脑的组合非常实用。比如我做过一个原型出差的时候问大模型我现在适合出去吃饭还是再等半小时它真的会去读手机的实时定位和附近的 POI 数据再结合时间给建议。但在原生 App 里跑 Server 没这么轻松。iOS 沙箱不允许 App 随意绑定端口Android 倒是可以开一个 ServerSocket但后台随即被 Doze 限制。更工程化的做法是用 C 或 Rust 把 MCP Server 编译成静态库打进 App通过本地回环通信或者直接在一个 WebSocket Server 里封装 MCP。我这里有一个简化版的思路在 App 里内置一个 WebSocket 服务端MCP 的 JSON-RPC 消息走 WebSocket 帧客户端用浏览器或桌面程序直接连。这样既绕开了端口监听限制又保留了两个方向的消息能力。2.3 电脑端做跳板把真机当 MCP 工具的对象这是当前最成熟、使用人数最多的 mobile-mcp 用法——电脑上的 MCP Server 负责和手机通信大模型把手机当作一个可操作对象。本质上是测试自动化和设备控制的 MCP 化。具体链路是这样的电脑上跑一个 MCP ServerServer 内部通过 adb安卓或者 libimobiledeviceiOS和手机建立一条控制通道。Server 暴露的工具包括 get_screen截屏、click点击坐标、swipe滑动、read_ui读取当前 UI 层级、install_app安装应用。大模型看到的是一个普通的 MCP 工具列表但每次调用背后操作的是真实手机。这套方案的好处是模型不用跑在手机上电脑上的强大模型完全够用而且手机也不需要做任何改造开发者模式打开就行。我在做多机型兼容测试时一个模型实例可以同时挂五六台手机每台手机对应一组工具命名空间phone_1_click、phone_2_click模型自动调度效果非常震撼。缺点是有点慢一次截屏加上模型理解 UI 的时间大约两秒大规模跑用例的时候并发不够另外真机状态的随机性经常把模型整懵比如弹窗、通知挡住了关键按钮。2.4 如何选择适合自己的形态选型不用纠结我建议按三个维度去卡第一个是数据隐私要求。数据不能出设备就选手机当服务端的本地形态数据本身在云端就选手机当客户端要测试和操控真机就选电脑跳板。第二个是算力分布。手机上能跑得动小模型但不跑大模型理想情况是端侧算力和云端算力协同MCP 工具可以分布在两端Host 统一调度。我现在做的项目就是这个架构一个核心助手同时挂了三个 Server本地的设备能力 Server、云端的知识库 Server、以及一个测试专用的模拟器 Server。第三个是交付成本。如果你面向 C 端做 App手机当服务端意味着你要维护一整套端内通信和权限体系成本很高如果只是自己用或做内部工具电脑跳板一小时就能搭起来。3. 把手机能力封装成 MCP 工具3.1 工具梳理哪些能力值得暴露不是所有手机能力都适合做成 MCP 工具。我建议先画一张清单按调用的必要性和风险等级两个维度评估。下面是我整理过的一张能力对照表你直接拿来当模板用能力工具名称示例输出内容风险等级电池电量get_battery_status电量百分比、充电状态低设备位置get_current_location经纬度、城市名高网络状态get_network_infoWiFi/蜂窝、信号强度低通讯录search_contacts姓名、号码需脱敏极高日历事件list_calendar_events时间、标题、地点高系统通知get_recent_notifications应用名、摘要高剪贴板read_clipboard文本内容极高传感器get_sensor_data加速度、陀螺仪中相册list_photo_metadata缩略图、时间、位置极高应用列表get_installed_apps包名、版本中优先级上先把电量、网络、定位、传感器这些当前环境感知类的工具做出来因为它们的调用频率高、风险可控而且对模型提升场景理解帮助最大。通讯录和剪贴板这类高风险能力我建议放到第二阶段配合完善的授权提示再上。3.2 动手实现用官方 SDK 写一个端内 MCP Server我用 Node.js 和官方 SDK 写过一个小型 Server核心代码也就几十行。下面这个例子是在 Android 的 Termux 环境里跑的把电量读取封装成一个 MCP 工具import { McpServer } from modelcontextprotocol/sdk/server/mcp.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { z } from zod; const server new McpServer({ name: phone-tools, version: 0.1.0, }); server.registerTool( get_battery_status, { description: 读取当前设备电量百分比和充电状态, }, async () { // 在 Termux 里可以通过 dumpsys battery 读取 const output await exec(dumpsys battery); const level parseLevel(output); const charging parseCharging(output); return { content: [ { type: text, text: JSON.stringify({ level, charging }), }, ], }; } ); const transport new StdioServerTransport(); await server.connect(transport);这段代码跑node server.js后如果你的 Host比如 Claude Desktop支持 stdio 传输配置一行命令就能连上。但注意stdio 传输只适用于本地进程间——在手机里如果 Server 和 Host 在同一个 App 进程内用 stdio 没问题跨设备的话得换 Streamable HTTP 或者 WebSocket。如果走 HTTP 模式SDK 提供了 StreamableHTTPServerTransport配合 Fastify 就能跑一个监听端口的服务import express from express; import { StreamableHTTPServerTransport } from modelcontextprotocol/sdk/server/streamableHttp.js; const app express(); app.use(express.json()); app.post(/mcp, async (req, res) { const transport new StreamableHTTPServerTransport({ sessionIdGenerator: () randomUUID(), }); await server.connect(transport); // 将请求交给 transport 处理 }); app.listen(3000, () console.log(MCP server running on :3000));这一层代码本身没什么难度真正的难度在宿主的工程化。原生 App 里你不能直接跑 Node.js所以要么用 Termux 这种模拟终端环境要么把 Server 用 Rust 重写打进 App要么退一步用 WebSocket 方案让系统 WebView 去承载 JS 运行时。我吃过最后一种做法的亏WebView 在 App 切后台后资源会被回收MCP 连接瞬间全断必须做重连这个坑你在设计的时候就要预留接口。3.3 传输层选型与连接保活移动端传输层选型我建议按这个逻辑推首先是 stdio只用于端内同进程。其次是 Streamable HTTP这是官方目前的主推方案移动端也很合适因为它是标准的 HTTP 请求天然适配蜂窝网络的短连接特性不存在长连接被系统掐断的问题。再次是 WebSocket适合需要 Server 主动推送的场景比如通知订阅但移动端保活成本高省电模式下心跳包很快被限制最后是自定义 TCP 或 UDP除非你做的是完全可控的局域网工具否则不推荐移动网络穿透太痛苦。移动端保活的核心思路不是让连接不被断开而是断开后快速重建。我在 App 里做了一套连接管理器当 Host 发起请求时如果发现连接不存在立即尝试重连重连采用指数退避第一次 500ms第二次 1s到 30s 封顶同时监听网络变化广播Android 的 ConnectivityManager 或 iOS 的 NWPathMonitor网络恢复后立刻主动触发重连。这套机制上线后移动网络的请求失败率从 10% 左右降到 0.5%效果非常明显。还有一个小点蜂窝网络下不要让模型无限生成。MCP 工具返回的数据本身很小但模型拿到数据后可能开始长篇大论流量不知不觉就烧了。好的做法是在 Host 端对输出 token 数做限制尤其是移动端每轮对话限制在 300 token 以内体验是最好的。3.4 工具输出格式设计移动端工具输出比服务端更需要克制。模型上下文窗口是有限的你不可能把一个通讯录 800 个联系人的 JSON 全部塞给模型也没必要。我的原则是先摘要后详查。拿通讯录工具举例search_contacts 接口接收关键字返回最多 20 条联系人摘要每条只包含姓名前两个字、号码后四位、是否有头像不返回完整号码。如果模型确实需要完整号码再调用 get_contact_detail 拿明文而这个接口需要额外的指纹确认。这个设计既保证了模型能完成任务又把敏感数据的暴露范围缩到最小。更普适的做法是在返回结构里加一个 summarize 字段模型默认读摘要需要细节时再显式调用展开接口。我在位置工具里就是这么干的get_current_location 默认返回当前位于杭州市西湖区而不是一上来就把经纬度扔出来。模型处理起自然语言摘要比浮点数坐标容易得多人也好看懂。4. 权限、隐私与安全边界4.1 移动端的授权模型服务端的 MCP 安全可以靠内网隔离解决移动端不行你的 Server 访问的就是用户真实的隐私数据。我把安全设计拆成三层操作系统层、MCP 层、应用层。操作系统层是标准的运行时权限定位、通讯录、相册都必须向用户申请授权。这一层你躲不掉也不能躲——如果你绕过系统权限直接读数据App 会被商店审核直接毙掉而且 Android 的隐私保护机制也会在运行时拦截。MCP 层要做的是给每个 Tool 单独声明它需要的权限范围。比如一个 Server 同时暴露了 get_battery_status 和 search_contacts那么 Host 在调用 search_contacts 之前MCP 的 capabilities 协商阶段就应该返回 contacts.scope 之类的权限标识Host 侧据此弹出二次确认。这相当于在 MCP 协议内部自己做一层比系统权限更细的授权粒度到工具级而不是到 App 级。应用层则是业务逻辑比如登录用户等级决定能调用哪些工具VIP 用户可查更多历史记录等等。三层叠加下来才算得上完整的授权链。4.2 数据脱敏与最小化返回就算授权通过了返回给模型的数据也应该做脱敏。这不是不信任模型而是防止中间环节泄露。MCP 调用链可能经过云端的日志系统、第三方的网关任何一个环节记录下明文通讯录都是事故。我实践了几个脱敏规则效果不错手机号只返回后四位如 138****2372通讯录姓名只返回姓氏加星号如 张**位置经纬度四舍五入到小数点后一位误差在 10 公里级别仅用于天气、城市周边等粗粒度场景剪贴板优先使用 OS 的剪贴板权限提示读写都要明确的 UI 承诺相册只返回缩略图和拍摄时间不返回原图 URL除非专门走下载流程有一类数据我建议干脆不暴露给模型比如设备序列号、IMSI、Wi-Fi 密码、Keychain 里的敏感项。这些数据模型调用了也没实际用处只会增加风险。4.3 本地鉴权与访问控制如果你的 MCP Server 监听在局域网端口上那意味着同一 WiFi 下任何一个设备都能发请求。我在真机调试时用局域网连过被隔壁同事顺手调了一次工具接口幸好那个 Server 没有权限校验事后吓出一身冷汗。从那以后我的所有本地 Server 都加上了 Token 鉴权。实现方式很简单在 Streamable HTTP 的请求头里要求携带 Authorization: Bearer tokenServer 启动时生成 tokenHost 端在同机配置文件里引用。如果是跨设备token 通过安全通道分享比如扫码或者蓝牙配对。这个机制不复杂但能挡住 99% 的误触和好奇心访问。另外一个建议是不要把端口绑定到 0.0.0.0能绑 127.0.0.1 就绑 127.0.0.1只有真正需要物理机访问时才绑局域网。手机的本地端口容易被恶意 App 扫描绑定回环地址是最简单的隔离手段。5. 常见问题与排查技巧实录5.1 连接频繁断开、请求无响应这个是最常见的问题症状是 MCP 调用偶尔卡住几十秒然后超时。我排查下来原因大多是移动网络环境下的 TCP 连接被无声回收——Wi-Fi 切到蜂窝、进电梯、或者 App 切入后台连接断了自己都不知道。解决思路是三点。第一发起请求前先检查连接健康状态可以用一个轻量的 HTTP 探测第二会话需要幂等请求超时后可以安全重试不会重复操作比如转账类的工具就不要无脑重试第三利用系统的生命周期回调在 App 进入前台时主动触发一次 Server 重建。我还试过在手机端保持单一 WebSocket 长连接结果 Android 的 Doze 模式下系统很快就对心跳包失去耐心连接照样被掐。最终方案还是回到短请求 快速重建比硬保活可靠得多。5.2 工具调用超时或卡死移动端工具调用的超时问题大多发生在那些依赖系统 UI 的操作上比如相册选择器、相机拍照、剪贴板读取。这些操作在其他 MCP 工具里是 秒回在手机上却需要用户额外交互模型不知道就一直在等。我的处理是把所有涉及系统交互的工具都改成异步模式。Server 收到请求后立刻返回一个 task_id操作完成后再通过 WebSocket 推送结果或者由 Host 主动轮询。这需要 Host 端支持异步工具调用目前 MCP 协议对异步的支持还在演进中所以我的妥协方案是加一个长超时比如 60 秒同时在工具描述里明确告知模型这是一个需要用户确认的操作请耐心等待。实测下来模型在读到描述后很少误判超时。另一个坑是安卓的 MainThread 限制。如果你在原生端实现 Server直接在工具回调里访问 UI 相关状态很容易触发 NetworkOnMainThreadException 或者 UI 卡顿。务必把工具逻辑放到子线程回调回主线程更新状态。5.3 协议版本与 JSON Schema 问题MCP 协议还处于快速迭代期客户端和服务端版本不匹配非常常见。症状通常是 Host 提示server 返回了意外的 initialize 响应或者tool not found。我踩过的具体场景是客户端 SDK 是 1.x服务端是 0.9 的旧实现两边在 capabilities 协商时字段对不上导致工具列表拿不到。排查方法是先看 initialize 阶段的握手日志确认 serverInfo、protocolVersion、capabilities 三个字段都对齐。协议层面尽量跟进官方最新版不要自己魔改协议字段SDK 的版本号在 package.json 里锁定好。JSON Schema 的坑也有。移动端返回的数据经常是字符串拼接出来的 JSON而不是真正结构化的对象模型很容易解析失败。我后来统一在 Server 端用 zod 校验输出结构确保 content 的 type 字段和 text 字段一定存在再发给模型。这个小改动让下游模型的解析成功率明显提升。5.4 调试工具与日志体系移动端调试 MCP 比服务端麻烦因为你看不到服务端的 stdout。我攒了一套自己的调试流程第一步日志即协议。我在 Server 端把所有收发消息都打日志包括 initialize、tools/list、tools/call 的消息体。真机调试时把日志输出到文件跑完一轮场景直接拉日志文件分析。第二步用 MCP Inspector。这是官方给的调试面板可以手动调用工具、查看返回、测试 schema我在做 Server 端开发时基本离不开它尤其在真机连不上时先在模拟器里用它把逻辑调通。第三步模拟弱网。移动端问题有一大半是网络问题所以我在测试机上用开发者选项里的网络限速比如设置 3G 延迟和丢包跑完整流程确保弱网下调用链不断。这个测试做完基本上线后的问题能少一半。第四步做一张错误码表。给 Server 定义好结构化错误码比如 1001 表示授权失败1002 表示设备能力不可用1003 表示超时。Host 端按错误码走不同的重试和提示策略而不只是显示一行冷冰冰的 Server error。我给项目配了下面这张速查表你可以直接参考错误码含义处理建议1001权限不足引导用户去系统设置开启权限1002传感器或模块不可用提示设备不支持降级到替代方案1003操作超时指数退避重试最多 3 次1004请求参数不合法检查 JSON Schema修正后重试1005协议版本不兼容提示客户端升级 SDK6. 踩过几轮坑之后我想说的几件事做 mobile-mcp 这一年最大的体会是移动端的 MCP 不能照搬服务端的最佳实践它本质上是另一个物种。服务端你追求高并发和低延迟移动端你必须先解决生命周期、权限、弱网、耗电这些听起来很非 AI的问题。我建议任何想做这个方向的人都先从一个小工具集开始比如电量加定位两个工具先跑通不要一上来就全能力上齐。工具越多权限面就越大出事的概率也越高。还有一个细节是测试机器的选择。我在红米这种千元机上和旗舰机上跑同一个 Server性能差距非常大低端机上 JSON Schema 校验这种 CPU 密集操作都能吃满一个核。如果你要上线兼容性测试一定用低端真机跑别只在模拟器里自嗨。最后分享一个小技巧把手机 MCP Server 当作一个独立进程看待给它单独的配置目录、日志文件、状态文件。即使宿主 App 崩溃重启Server 也能恢复会话。我把它做成了模块化组件今天换 Host、明天换模型完全不影响已有的工具集。这样一套搭下来后续每次新增设备能力都只是往工具清单里加一行调用的事整个体系会越用越顺手。
