将设备暴露为 MCP 服务

MCP（Model Context Protocol）是一套协议标准，让 AI 模型可以与外部工具和能力进行交互。

Midscene 提供了 MCP 服务，可以将 Midscene Agent 中的原子化操作（即 Action Space 中的每个 Action）暴露为 MCP 工具，让上层 Agent 可以通过自然语言来查看界面、精准操作 UI 界面、执行自动化任务等，而无需理解复杂的底层实现。

由于 Midscene Agent 依赖于多模态模型，因此你需要在 MCP 服务中配置 Midscene 所需的环境变量，而不是复用上层 Agent 的模型配置。

MCP 工具列表

工具名称	功能描述
设备连接，如 `web_connect`、`ios_connect`、`android_connect`、`computer_connect`	连接到目标设备，如浏览器、iOS 设备、Android 设备、电脑桌面
`take_screenshot`	获取最新截图
`assert`	基于自然语言断言当前页面/屏幕状态
设备操作	对应 Action Space 中的每个 Action，如 `Tap`、`Scroll` 等

查看执行报告

每次交互操作执行结束，都会生成一份 Midscene 任务报告。可直接在命令行打开：

open report_file_name.html

报告中包含了交互操作的详细信息，包括截图、操作日志、错误信息等，便于调试和问题排查。

配置 MCP

浏览器桥接模式

@midscene/web-bridge-mcp 支持将 Chrome 插件的桥接模式发布为 MCP 服务。

环境准备

参考 Chrome 桥接模式，确保浏览器插件可以启动。推荐开启后台桥接模式（Background Bridge），这样无需手动点击「允许连接」，且连接在后台持续运行，不会因关闭插件弹窗而断开。

后台桥接模式

开启后台桥接模式后，MCP 服务可以随时连接，无需用户手动干预。详见后台桥接模式。

配置

在 MCP 客户端中添加 Midscene Web Bridge MCP 服务器（ @midscene/web-bridge-mcp ）。其中模型配置的参数请参考模型策略。

{
  "mcpServers": {
    "midscene-web": {
      "command": "npx",
      "args": ["-y", "@midscene/web-bridge-mcp"],
      "env": {
        "MIDSCENE_MODEL_BASE_URL": "替换为你的模型服务地址",
        "MIDSCENE_MODEL_API_KEY": "替换为你的 API Key",
        "MIDSCENE_MODEL_NAME": "替换为你的模型名称",
        "MIDSCENE_MODEL_FAMILY": "替换为你的模型系列",
        "MCP_SERVER_REQUEST_TIMEOUT": "600000"
      }
    }
  }
}

iOS MCP 服务

环境准备

AI 模型服务：准备 OpenAI API Key 或其他支持的 AI 模型服务，更多信息参见模型策略。
设备环境：请按照 iOS 快速开始配置 WebDriverAgent、证书与设备连接，确保 WebDriverAgent 已正常运行。可以在 iOS Playground 中验证截图和基础操作是否正常。

配置

在 MCP 客户端中添加 Midscene iOS MCP 服务器（ @midscene/ios-mcp ）。其中模型配置的参数请参考模型策略。

{
  "mcpServers": {
    "midscene-ios": {
      "command": "npx",
      "args": ["-y", "@midscene/ios-mcp"],
      "env": {
        "MIDSCENE_MODEL_BASE_URL": "替换为你的模型服务地址",
        "MIDSCENE_MODEL_API_KEY": "替换为你的 API Key",
        "MIDSCENE_MODEL_NAME": "替换为你的模型名称",
        "MIDSCENE_MODEL_FAMILY": "替换为你的模型系列",
        "MCP_SERVER_REQUEST_TIMEOUT": "800000"
      }
    }
  }
}

Android MCP 服务

环境准备

AI 模型服务：准备 OpenAI API Key 或其他支持的 AI 模型服务，更多信息参见模型策略。
设备环境：请按照 Android 快速开始配置 adb 工具与设备连接，确保 adb devices 可以识别目标设备。可以用 Android Playground 获取截图并执行简单操作来检验环境。

配置

在 MCP 客户端中添加 Midscene Android MCP 服务器（ @midscene/android-mcp ）。其中模型配置的参数请参考模型策略。

{
  "mcpServers": {
    "midscene-android": {
      "command": "npx",
      "args": ["-y", "@midscene/android-mcp"],
      "env": {
        "MIDSCENE_MODEL_BASE_URL": "替换为你的模型服务地址",
        "MIDSCENE_MODEL_API_KEY": "替换为你的 API Key",
        "MIDSCENE_MODEL_NAME": "替换为你的模型名称",
        "MIDSCENE_MODEL_FAMILY": "替换为你的模型系列",
        "MCP_SERVER_REQUEST_TIMEOUT": "800000"
      }
    }
  }
}

电脑桌面 MCP 服务

@midscene/computer-mcp 支持将电脑桌面自动化能力发布为 MCP 服务，让 AI 可以通过鼠标、键盘和截图操作来控制你的电脑。

环境准备

AI 模型服务：准备 OpenAI API Key 或其他支持的 AI 模型服务，更多信息参见模型策略。
系统权限：在 macOS 上，需要授予运行 MCP 服务的终端或应用程序辅助功能和屏幕录制权限。

配置

在 MCP 客户端中添加 Midscene Computer MCP 服务器（ @midscene/computer-mcp ）。其中模型配置的参数请参考模型策略。

{
  "mcpServers": {
    "midscene-computer": {
      "command": "npx",
      "args": ["-y", "@midscene/computer-mcp"],
      "env": {
        "MIDSCENE_MODEL_BASE_URL": "替换为你的模型服务地址",
        "MIDSCENE_MODEL_API_KEY": "替换为你的 API Key",
        "MIDSCENE_MODEL_NAME": "替换为你的模型名称",
        "MIDSCENE_MODEL_FAMILY": "替换为你的模型系列",
        "MCP_SERVER_REQUEST_TIMEOUT": "800000"
      }
    }
  }
}

提升精度（深度定位 / 深度思考）

有两个相互独立的启动参数，可在 MCP 服务处理任务遇到困难时使用：

--deep-locate（深度定位）：额外进行一轮视觉推理，以精确定位目标元素。当点击或交互落到错误位置（定位漂移或偏移）时，可以使用该参数。它作用于所有需要定位元素的操作，包括 Tap、Input、Scroll 等 Action 工具，以及 act 内部发生的定位。
--deep-think（深度思考）：让 act 工具以更深的推理来规划，提供更丰富的上下文和子目标拆解。它适用于复杂、多步的 act 指令。该参数只影响规划，因此对单步 Action 工具无效。

两者都用少量速度换取更好的效果，且可以同时开启。开启后，相关工具会默认使用对应能力，无需在每次调用时单独传参。

对于 MCP server，把参数加到 args 中：

{
  "mcpServers": {
    "midscene-android": {
      "command": "npx",
      "args": ["-y", "@midscene/android-mcp", "--deep-locate", "--deep-think"],
      "env": {
        "MIDSCENE_MODEL_BASE_URL": "replace with your model service URL",
        "MIDSCENE_MODEL_API_KEY": "replace with your API Key",
        "MIDSCENE_MODEL_NAME": "replace with your model name"
      }
    }
  }
}

同样的参数对 Agent Skill / 设备 CLI(midscene-android、midscene-web、midscene-ios 等)同样生效,因为它们共用同一套工具定义:

midscene-android --deep-locate tap --locate "登录按钮"

单次调用的取值始终优先于启动参数:Action 工具支持 locate.deepLocate,act 工具支持顶层的 deepLocate 与 deepThink 布尔参数,因此任意单次调用都可以无视启动设置自行开启或关闭。

按单次调用配置 Agent 行为

MCP 工具和设备 CLI 也支持通用的 Agent 行为参数。如果目标 UI 需要更长的稳定等待时间、不同的 act 重规划上限、额外的动作上下文，或需要压缩截图，都可以使用这些参数。这些参数是 API 公共参考中同名 Agent options 的单次调用写法。

在设备 CLI 中，把 API 里的 camelCase 参数名转换成不带平台前缀的 kebab-case flag，并加到需要生效的命令上。生成的 CLI 也接受 --help 中展示的 camelCase alias，但文档和示例统一使用 kebab-case：

midscene-android tap --locate "登录按钮" --wait-after-action 800
midscene-web act --prompt "完成结账" --replanning-cycle-limit 30
midscene-ios assert --prompt "成功提示可见" --screenshot-shrink-factor 2

通用参数：

--wait-after-action <ms> 对应 waitAfterAction：每次动作执行后的等待时间，默认值为 300。
--replanning-cycle-limit <n> 对应 replanningCycleLimit：aiAct 的最大重规划次数。
--ai-act-context <text> 对应 aiActContext：传给 aiAct 的额外背景信息。
--screenshot-shrink-factor <n> 对应 screenshotShrinkFactor：发送给 AI 模型前的截图压缩倍率。

在 MCP 调用中，保留 API 里的 camelCase 参数名，并放在平台 namespace 下：android.waitAfterAction、harmony.waitAfterAction、ios.waitAfterAction、computer.waitAfterAction 或 web.waitAfterAction。replanningCycleLimit、aiActContext 和 screenshotShrinkFactor 也使用同样的规则。

这些参数属于当前工具调用的 Agent init args。后续调用如果改变这些参数，或在设置后省略它们，Midscene 会重建 Agent，让下一次调用使用新的有效配置。对于 Web 工具，只要传入 web.url，每次都会打开或导航到该 URL；省略它则继续使用当前页面。

实现自己的 MCP

如果你想在自己的 MCP 服务中集成 Midscene 工具，可以使用 mcpKitForAgent 函数来获取工具定义，继而自己按需暴露 MCP 服务。

mcpKitForAgent 提供的工具包括截图与 Action Space 中的每个 Action。

使用 mcpKitForAgent

mcpKitForAgent 函数接受一个 Agent 实例，返回包含描述和工具列表的对象：

import { mcpKitForAgent } from '@midscene/web/mcp-server';
import { Agent } from '@midscene/core/agent';

const agent = new Agent();
const { description, tools } = await mcpKitForAgent(agent);

// description - "Control the browser / device using natural language commands"
// tools - Tool[] - 工具定义数组

平台支持

每个平台都提供了对应的 mcpKitForAgent 函数：

Web 平台

import { mcpKitForAgent } from '@midscene/web/mcp-server';

iOS 平台

import { mcpKitForAgent } from '@midscene/ios/mcp-server';

Android 平台

import { mcpKitForAgent } from '@midscene/android/mcp-server';

Computer 平台

import { mcpKitForAgent } from '@midscene/computer/mcp-server';

集成到自定义 MCP 服务

你可以将获取的工具集成到自己的 MCP 服务中：

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { mcpKitForAgent } from '@midscene/web/mcp-server';

const agent = new Agent();
const { description, tools } = await mcpKitForAgent(agent);
const server = new McpServer({
  name: 'my-custom-mcp',
  version: '1.0.0',
  description
});

// 注册 Midscene 工具到你的 MCP 服务
for (const tool of tools) {
  server.tool(tool.name, tool.description, tool.schema, tool.handler);
}

#将设备暴露为 MCP 服务

#MCP 工具列表

#查看执行报告

#配置 MCP

#浏览器桥接模式

#iOS MCP 服务

#Android MCP 服务

#电脑桌面 MCP 服务

#提升精度（深度定位 / 深度思考）

#按单次调用配置 Agent 行为

#实现自己的 MCP

#使用 mcpKitForAgent

#平台支持

#集成到自定义 MCP 服务

将设备暴露为 MCP 服务

MCP 工具列表

查看执行报告

配置 MCP

浏览器桥接模式

iOS MCP 服务

Android MCP 服务

电脑桌面 MCP 服务

提升精度（深度定位 / 深度思考）

按单次调用配置 Agent 行为

实现自己的 MCP

使用 mcpKitForAgent

平台支持

集成到自定义 MCP 服务