#将设备暴露为 MCP 服务

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

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

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

#MCP 工具列表

#查看执行报告

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

open report_file_name.html

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

#配置 MCP

#浏览器桥接模式

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

环境准备

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

配置

在 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 布尔参数,因此任意单次调用都可以无视启动设置自行开启或关闭。

#实现自己的 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);
}