UI Explorer MCP Server

UI Explorer MCP 服务

一个 MCP 服务，提供用于探索和交互屏幕上 UI 元素的工具。

功能

• 探索 UI 层级：扫描并分析屏幕上的所有 UI 元素
• 为 UI 截图并添加高亮：通过边界和层级直观显示 UI 元素
• 控制鼠标点击：根据坐标点击 UI 元素
• 探索特定区域：聚焦屏幕的特定部分，例如左上角、中心等
• 🎬 宏录制：独立录制和播放 UI 工作流，或通过 MCP 录制和播放

🚀 快速开始：独立宏录制

**新增！**现在无需运行 MCP 服务即可录制 UI 工作流：

# Record a workflow
python record_macro.py --name "Login Workflow"

# Play it back
python play_macro.py --file "macros/Login Workflow.json"

Windows 用户可以使用批处理文件：

record_macro.bat "My Workflow"
play_macro.bat "macros/My Workflow.json"

👉 参阅 QUICK_START.md，了解 2 分钟教程 👉 参阅 MACRO_TOOLS.md，了解完整文档

会录制哪些内容？

• ✅ 带精确坐标的鼠标点击
• ✅ 采用智能文本缓冲的键盘输入
• ✅ 确保可靠播放的 UI 上下文
• ✅ 用于验证的屏幕截图
• ✅ 确保自然回放的时间信息

录制控制

• F9：开始/停止录制
• F10：暂停/恢复
• ESC：紧急停止

安装选项

选项 1：使用 pip（推荐）

全局安装软件包，或将其安装在虚拟环境中：

pip install mcp-ui-explorer

选项 2：使用 git clone

1. 克隆仓库：

git clone https://github.com/modularflow/mcp-ui-explorer
cd mcp-ui-explorer

2. 安装软件包：

   • 使用 pip 以开发模式安装：

   pip install -e .
   

   • 或使用 uv（推荐用于开发）：

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv pip install -e .
   

MCP 服务配置

安装软件包后，需要配置 MCP 客户端以使用 UI Explorer 服务。

在 Cursor 中使用 Roo

将以下 JSON 添加到 MCP 服务配置文件中： C:\Users\<user_name>\AppData\Roaming\Cursor\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json

{
  "mcpServers": {
    "ui-explorer": {
      "command": "uvx",
      "args": [
        "mcp-ui-explorer"
      ]
    }
  }
}

用于 Claude Desktop App

将服务配置添加到： C:\Users\<user_name>\AppData\Roaming\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ui-explorer": {
      "command": "uvx",
      "args": [
        "mcp-ui-explorer"
      ]
    }
  }
}

使用 uvx 直接运行

如果已安装软件包（无论是全局安装还是安装在虚拟环境中），都可以直接使用 uvx 运行服务，无需额外配置：

uvx mcp-ui-explorer

MCP 工具

UI Explorer 提供多个用于 UI 自动化和探索的 MCP 工具。使用 MCP 服务接口时即可使用这些工具。

使用指南

1. 探索 UI 结构

使用 explore_ui 工具获取完整的 UI 元素层级：

参数：

• region：要分析的屏幕区域（"screen"、"top"、"bottom"、"left"、"right"、"center" 等）
• depth：要分析的最大层级深度（默认值：5）
• min_size：要包含的最小元素尺寸（默认值：5px）
• focus_window：仅分析前台窗口（默认值：False）
• visible_only：仅包含屏幕上可见的元素（默认值：True）
• control_type：要搜索的控件类型（默认值："Button"）
• text：按文本内容筛选元素（可选）

2. 截取突出显示 UI 元素的屏幕截图

使用 screenshot_ui 工具直观显示 UI 元素：

参数：

• region：要分析的屏幕区域
• highlight_levels：为不同层级使用不同颜色（默认值：True）
• output_prefix：输出文件的前缀（默认值："ui_hierarchy"）

3. 点击屏幕坐标

使用 click_ui_element 工具点击特定坐标：

参数：

• x：要点击的 X 坐标（必填）
• y：要点击的 Y 坐标（必填）
• wait_time：点击前等待的秒数（默认值：2.0）

4. 键盘输入和快捷键

该工具还提供键盘输入和快捷键选项。详情请参阅 MCP 接口中的 UI Explorer 指南。

示例工作流

1. 首先，探索界面，了解屏幕上的内容：

   explore_ui(region="screen", control_type="Button")
   

2. 截取屏幕截图，以查看界面元素：

   screenshot_ui(region="screen")
   

3. 记下要点击的元素的坐标，然后点击对应坐标：

   click_ui_element(x=500, y=300)
   

4. 根据需要输入文本或使用键盘快捷键：

   keyboard_input(text="Hello world", press_enter=true)
   

要求

• Windows 操作系统
• Python 3.10+
• MCP 1.6.0+
• PyAutoGUI
• PyWinAuto
• Pillow
• Pydantic 2.0+