Windows 365 for Agents MCP 服务器参考（预览版）

Windows 365 for Agents 是一台 MCP 服务器，用于对 Windows 365 云 PC 进行全面运营控制。 利用这个MCP服务器通过桌面交互（鼠标、键盘、屏幕截图、命令执行）、通过Microsoft Edge实现浏览器自动化以及通过Windows UI 自动化进行语义UI检查，驱动真实的Windows环境。

如需了解更多关于代理的 Windows 365，请参见代理文档Windows 365。

Overview

Available tools

mcp_desktop_move_mouse

把光标移到屏幕位置。 如果你打算点击目的地，就用它 mcp_desktop_click 代替。 Required parameters:

• x：x坐标（屏幕像素）
• y：Y坐标（屏幕像素）

mcp_desktop_click

点击某个位置，或者如果省略坐标，则点击当前光标位置。 支持单击、双击以及全部五个鼠标按键。

Optional parameters:

• x：X坐标（屏幕像素数）（省略当前位置）
• y：屏幕像素中的Y坐标（当前位置省略）
• 按键：左、右、中、前或后（默认左）
• 点击计数：1 = 单击，2 = 双击（默认 1）

mcp_desktop_get_cursor_position

返回当前光标坐标。 No parameters. 返回{cursorX， cursorY}。

mcp_desktop_drag_mouse

从一个位置拖到另一个位置。 它适合移动物体、调整窗口大小或像素精确滚动。 Required parameters:

• startX：开始X坐标。
• startY：开始Y坐标。
• endX：结束X坐标。
• endY：结束Y坐标。 Optional parameters:
• 按钮：左、右或中（默认为左）

mcp_desktop_scroll

在某个位置滚动时，使用缺口单位（不是像素）。 三刻痕大约相当于一页。

Required parameters:

• x：卷轴位置 x
• y：卷轴位置 Y

Optional parameters:

• deltaX：水平缺口，正 = 右（默认 0）
• deltaY：垂直凹槽，正=向下（默认0）

Note

数值被限制在 [-20， 20] 范围内。

mcp_desktop_type_text

通过键盘模拟输入文字。 键盘快捷键请使用 mcp_desktop_press_keys。 对于网页表单字段，请使用 mcp_browser_type。

Required parameters:

• 文本：文字输入

mcp_desktop_press_keys

同时按下一个按键组合。 支持修饰键、功能键和标准键。

Required parameters:

• 键：按键名称数组，按键组合（例如， ["ctrl","c"]， ["alt","tab"]， ["ctrl","shift","s"]）

mcp_desktop_take_screenshot

将全屏或裁剪区域捕捉为PNG图像（base64编码）。

Optional parameters:

• x：裁剪区域左边
• y：裁剪区域顶部边缘
• 宽度：裁剪区域宽度
• 高度：作物区域高度

Note

可以同时提供四个裁剪参数，或者全屏截图时省略四个参数。

mcp_desktop_zoom_region

以原生分辨率捕捉屏幕区域，作为 PNG 图像（base64 编码）。 用它来检查那些在缩小全屏截图中难以辨认的小文字或密集的用户界面。

Required parameters:

• x：左边 X 坐标（屏幕像素）
• y：屏幕像素中的顶边Y坐标
• 宽度：区域宽度（像素单位）
• 高度：区域高度（像素单位）

Note

最大区域大小为1920x1080像素。

mcp_desktop_analyze_screen

对整个屏幕进行OCR检测。 No parameters. 返回 {fullText, averageConfidence, boxes[{text, confidence, x, y, width, height}], width, height}。

mcp_desktop_get_screen_size

恢复屏幕分辨率。 No parameters. 返回 {width, height}。

mcp_desktop_list_windows

列出所有可见的窗口及其标题、位置和尺寸。 No parameters. 返回数 {title, processName, handle, x, y, width, height}组。

mcp_desktop_activate_window

用模糊的冠军赛把窗户带到前景。

Required parameters:

• titlePattern：部分窗口标题（大小写不区分子字符串）

mcp_desktop_focus_browser

聚焦于浏览器窗口（Edge、Chrome 或 Firefox），可选择按 URL 或标题过滤。

Optional parameters:

• 模式：URL或标题子串匹配（任何浏览器窗口省略）

mcp_desktop_close_window

优雅地通过模糊的冠军赛关闭了一扇窗。 系统关键进程受到保护，无法关闭。

Required parameters:

• titlePattern：部分窗口标题（80% 匹配阈值）。 返回 {matchedTitle, processName, closed}。

mcp_desktop_resize_window

使用模糊标题匹配调整、移动、最大化、最小化或恢复窗口大小。

Required parameters:

• 标题：窗口标题匹配（大小写不相关模糊匹配）
• 动作：执行 — Resize、 Move、 MaximizeMinimize、 或Restore

Optional parameters:

• x：左边 X 坐标（用于 Resize 或 Move）
• y：顶边Y坐标（用于缩放或移动）
• 宽度：像素宽度（用于Resize）
• 高度：以像素为单位的高度（与Resize一起使用）

mcp_desktop_execute_shell_command

在沙盒环境中运行一个shell命令。 命令会根据允许列表进行验证，并阻止危险模式。

Required parameters:

• 命令：执行命令

Optional parameters:

• cwd：工作目录。 使用前斜斩（例如， C:/Users/me/project）。
• timeoutMS：以毫秒计的超时（默认30000，最大30000）

Note

• 允许的命令有：git、npm、dotnet、python、cargo、node、pip、dir、mkdir、del、copy、move、robocopy、findstr、where、type、notepad。
• 阻塞模式包括shell元字符（|、;、&、 <）、 >环境变量展开 (%VAR%)、解释器评估标志（python -c 或 node -e）、 git config --global、 npm -g、路径前缀可执行文件、 rm -rf、、 sudo以及磁盘/系统命令。
• stdout 每个 stderr 都截断为32 KB。 用于 mcp_desktop_execute_python_code 任意计算。 返回 {stdout, stderr, exitCode, success, timedOut, resourceLimitsApplied}。

mcp_desktop_execute_python_code

在资源有限的沙箱环境中执行Python代码。 非常适合数据处理、计算、文件输入输出以及任何超出简单shell命令的计算。

Required parameters:

• code：Python码（最大262,144字符）。

Optional parameters:

• cwd：工作目录。 用前斩。
• timeoutMs：以毫秒计的超时（默认30000，最大30000）。

返回与 mcp_desktop_execute_shell_command相同的模式。

Note

沙盒强制执行512 MB内存限制和30秒超时。

mcp_desktop_wait_milliseconds

暂停执行以让动画或过渡完成。 不要在轮询循环中使用——用于 mcp_browser_wait_for DOM轮询。

Required parameters:

• ms：等待时间（以毫秒计）（锁定为[0， 5000]）

mcp_desktop_clipboard_read

阅读系统剪贴板的最新内容。 No parameters. 返回描述剪贴板格式和有效载荷的JSON对象——文本字符串或base64编码的图像。

mcp_desktop_clipboard_write

将文本写入系统剪贴板，替换当前内容。

Required parameters:

• 文本：写到剪贴板的文字

返回确认，包括字符数。

mcp_desktop_list_processes

列出当前会话中的正在运行进程。 每个条目包含PID、进程名称、内存使用情况、窗口标题（如有）和 startTimeTicks。 配合startTimeTicksmcp_desktop_kill_process使用以防止循环再利用的PID被杀死。

Optional parameters:

• maxCount：返回的最大进程数（默认200）

返回一个 JSON 数组的进程信息对象。

mcp_desktop_kill_process

通过PID终止进程。 startTime必须提供该mcp_desktop_list_processes价值以防PID回收。

Required parameters:

• pid：进程ID 返回 mcp_desktop_list_processes
• startTime：处理启动时间tick返回 mcp_desktop_list_processes

Optional parameters:

• 原力：无优雅关闭（默认为false）的原力杀死

返回描述结果的 JSON 结果。

mcp_desktop_launch_application

从允许的目录启动 GUI 应用程序。 改用 mcp_desktop_execute_shell_command CLI命令。

Required parameters:

• path：指向可执行文件的绝对路径。 使用前斜斩（例如， C:/Program Files/app.exe）。

Optional parameters:

• args：命令行参数数组

返回 {path, pid}。

mcp_desktop_get_system_info

返回操作系统版本、CPU、内存、可用磁盘空间和显示分辨率。 No parameters. 返回包含系统信息的 JSON 对象。

mcp_browser_navigate

导航到一个网址，等待页面加载。

Required parameters:

• URL：完整 URL 包含协议（例如， https://example.com）

mcp_browser_back

回到浏览器历史中。 No parameters.

mcp_browser_forward

在浏览器历史中向前导航。 No parameters.

mcp_browser_reload

重新加载当前页面。 No parameters.

mcp_browser_get_url

返回当前页面的URL作为普通字符串。 No parameters.

mcp_browser_get_title

将当前页面标题以普通字符串返回。 No parameters.

mcp_browser_get_text

将可见的页面文本内容以纯字符串返回。 No parameters. 截断为512 KB。

mcp_browser_get_html

返回整页HTML源代码为普通字符串。 No parameters. 截断为512 KB。

mcp_browser_click

通过CSS选择器点击DOM元素。 比基于坐标点击网页内容更可靠。

Required parameters:

• 选择器：CSS 选择器（例如， #submit-btn 或 a.nav-link）

mcp_browser_type

通过 CSS 选择器将文本输入表单元素。

Required parameters:

• 选择器：输入元素的 CSS 选择器。
• 文本：文字输入

mcp_browser_query_text

获取第一个元素的文本内容，匹配CSS选择器。

Required parameters:

• 选择器：CSS 选择器

mcp_browser_wait_for

等待DOM元素出现。 对于异步加载的动态内容非常有用。

Required parameters:

• 选择器：CSS 选择器以等待

Optional parameters:

• timeoutMs：超时（毫秒）（默认5000，最大30000）

mcp_browser_eval_js

在页面上下文中评估一个JavaScript表达式，并返回字符串。

Required parameters:

• 表达式：返回字符串的JavaScript表达式

Note

如果你的表达式返回对象或数字，显式转换为字符串（例如， JSON.stringify(obj) 或 .toString()）。

mcp_browser_list_tabs

列出所有打开的标签页及其索引、标题和网址。 No parameters. 返回数 {index, title, url}组。

mcp_browser_switch_tab

通过索引切换到制表表。

Required parameters:

• tabIndex：基于0的标签索引

mcp_browser_new_tab

打开一个新标签页，可选择访问URL。

Optional parameters:

• URL：打开的URL（若省略，则为空白标签）

返回 {index, title, url}。

mcp_browser_close_tab

按索引关闭标签页。

Required parameters:

• tabIndex：基于0的标签索引

mcp_browser_screenshot

只截取浏览器视口的PNG截图（不包括全屏）。 No parameters. 返回一个base64编码的PNG。

mcp_browser_select_option

通过属性value选择一个或多个元素中的<select>选项。

Required parameters:

• 选择器：元素的 <select> CSS 选择器
• 值：选择选项值数组

返回确认，显示所选选项的数量。

mcp_browser_fill_form

一次通话中填写多个表格字段。 每条条目都是一 {selector, value} 对。 首次失败时停靠并报告成功的场地。

Required parameters:

• 字段：对数组{selector, value}

返回已填充字段数的确认。

mcp_browser_drag

将源元素拖拽到目标元素上。 这两个元素都由 CSS 选择器识别。

Required parameters:

• sourceSelector：拖拽源代码的 CSS 选择器
• targetSelector：投放目标的CSS选择器

mcp_browser_pdf_save

将当前页面保存为PDF文件。 目标路径被限制为 %USERPROFILE% 或 %TEMP%。

Required parameters:

• filePath：目标文件路径，位于 %USERPROFILE% 或 %TEMP%。 用前斩。

返回确认，包括保存的文件路径。

mcp_browser_handle_dialog

接受或关闭待处理的浏览器对话框（提醒、确认、提示或卸载前）。 如果没有对话处于激活状态，则返回“无待处理对话”。

Required parameters:

• 动作： accept 或 dismiss

Optional parameters:

• promptText：用于提示对话框的文本（在提醒和确认时忽略）

mcp_browser_snapshot

用稳定的参考编号（例如） e5捕捉页面的可访问性树，这些 ID 映射到 DOM 节点。 使用带有 mcp_browser_click_ref、 mcp_browser_type_ref和 mcp_browser_hover_ref的参考。 参考文献在页面导航时失效——导航后请重新截图。

Optional parameters:

• maxDepth：最大树木深度，1-10（默认5）
• includeIframes：包含跨原点iframes（默认true）

返回包含无障碍快照和ref ID的JSON对象。

mcp_browser_click_ref

通过ref ID mcp_browser_snapshot点击元素。 命中测试验证没有其他元素覆盖目标。 如果快照已过期，则失败——此时请重新拍摄快照。

Required parameters:

• snapshotId：快照ID 返回 mcp_browser_snapshot
• ref：来自快照节点的元素ref（例如）， e5

Optional parameters:

• 按键：左、右或中（默认左）
• 点击计数：1 = 单击，2 = 双击（默认 1）

返回确认，包含点击的坐标。

mcp_browser_type_ref

通过引用 ID mcp_browser_snapshot在元素中输入文本。 元素先被聚焦，默认清除现有文本。 如果快照已过期，则失败。

Required parameters:

• snapshotId：快照ID 返回 mcp_browser_snapshot
• ref：来自快照节点的元素ref（例如）， e5
• 文本：文字输入

Optional parameters:

• clear：先清除现有文本（默认为真）

返回确认，包括字符数。

mcp_browser_hover_ref

通过参考编号 mcp_browser_snapshot将鼠标悬停在元素上。 Returns immediately. 如果快照已过期，则失败——此时请重新拍摄快照。

Required parameters:

• snapshotId：快照ID 返回 mcp_browser_snapshot
• ref：来自快照节点的元素ref（例如）， e5

返回包含悬停坐标的确认。

mcp_accessibility_get_accessibility_tree

获取前景窗口的UI元素树。 每个元素都包含其角色、名称、数值和屏幕坐标。

Optional parameters:

• maxDepth：最大树木遍历深度，1-10（默认3）
• maxElements：返回的最大元素数，1-2000（默认500）

返回一个层级树，包含{role， name， value， x， y， width， height， children[...]}。

mcp_accessibility_find_ui_element

通过文本内容、无障碍角色或名称（大小写不区分子串）搜索 UI 元素。 返回匹配元素及其可点击的屏幕坐标。

Optional parameters:

• 文本：用于搜索的文本（若省略姓名，则用作名称）
• 角色：UI角色筛选器——Button、CheckBoxTextBoxMenuItemComboBox等
• 名称：可访问名称（如果两者都提供，优先于文本）
• windowHandle：目标窗口句柄（null = 前景窗口）

Key features

Desktop interaction

• 点击、双击、右键和五键鼠标控制。
• 像素级精确拖放。
• 基于刘海滚动（一页三个刘海≈）。
• 键盘打字和多键快捷键组合。
• 光标位置追踪。
• 屏幕分辨率检测。

截图与分析

• 全屏或裁剪的PNG截图。
• 全屏OCR显示，包含各区域置信度分数和边界框。
• 网页内容仅可通过浏览器视口截图。

Window management

• 列举所有可见的窗口，并标明位置和尺寸。
• 通过模糊标题匹配激活Windows。
• Focus浏览器窗口（Edge、Chrome、Firefox），可选通过URL或标题筛选。
• 优雅关闭窗口，保护系统关键流程。

Command execution

• 带有允许列表（git, npm, dotnet, python, cargo, node, pip, dir, mkdir, del, copy, move, robocopy, findstr, where, type）的沙箱shell命令。
• 沙箱Python执行最多262,144字符的代码。
• 工作目录控制和每次呼叫超时控制（最多30秒）。
• 资源限制和针对shell元字符、评估标志、权限升级和破坏性操作的强化屏蔽列表。

Browser automation

• 导航，后退，前进，装填。
• 阅读页面URL、标题、可见文本（512 KB上限）和完整HTML（512 KB上限）。
• 通过 CSS 选择器进行 DOM 级别的点击、输入和文本查询。
• 等待带有可配置超时的动态元素。
• 在页面上下文中评估 JavaScript 表达。
• 多标签管理：列表、切换、打开、关闭。
• 运行在 Microsoft Edge 上，首次使用时自动启动。

UI accessibility

• 获取前景窗口的Windows UI 自动化 tree，并可配置深度和元素数量。
• 按文本、角色或可访问名称查找界面元素。
• 返回可点击的屏幕坐标，用于精确定位按钮、文本框、复选框、菜单项和组合框。

时序与同步

• 短暂的单次暂停 mcp_desktop_wait_milliseconds （最多五秒）。
• DOM级别轮询通过 mcp_browser_wait_for （最长30秒）。

Notes

• 所有坐标均以屏幕像素为单位，左上角为（0,0）。 来自 mcp_desktop_take_screenshot、 mcp_desktop_analyze_screen、 mcp_accessibility_find_ui_element和 mcp_desktop_list_windows 的坐标共享相同的坐标空间。
• 光标保险机制是激活的：如果光标距离任何屏幕角落以内五个像素，鼠标操作将被取消。 避免瞄准屏幕的极端边缘。
• 壳管运算符（|）、分号（;)、&符号（&）和输出重定向（>， <）被阻塞。 要转换命令输出，捕获并用 mcp_desktop_execute_python_code处理。
• 如果解释器评估标志被阻挡，或者拒绝python -c "..."和node -e "..."，你可以用mcp_desktop_execute_python_code来处理Python代码，或者先写代码到文件。
• 命令 stdout/stderr 每个截断为32 KB。 使用标志来限制冗长输出（例如， git log --oneline -20），或重定向到文件并单独读取。
• 和 mcp_desktop_execute_shell_command 的最大超时mcp_desktop_execute_python_code时间为 30 秒。 如果要做较长的工作，可以把它拆成更小的步骤，或者用Python启动一个后台进程并进行投票。
• 没有专门的文件读写工具。 使用mcp_desktop_execute_shell_command命令读取带有type的文件;使用Python内置的文件输入输出（I/O）写入带有mcp_desktop_execute_python_code的文件。 Shell 输出重定向>（， >>）被阻断。
• mcp_browser_eval_js 总是返回字符串。 在返回前明确转换对象或数字。
• 浏览器的DOM工具（mcp_browser_click、mcp_browser_type、mcp_browser_eval_js等）只在Microsoft Edge实例上工作。  mcp_desktop_focus_browser 可以聚焦 Chrome 或 Firefox 窗口，但 DOM 工具无法针对它们。
• mcp_desktop_take_screenshot 全屏截图需要同时处理四个参数（x、y、宽度、高度），或者全屏截图时不需。
• mcp_desktop_scroll 使用缺口单元（固定在[-20， 20]），而非像素。 三刻痕大约相当于一页。
• mcp_accessibility_find_ui_element 至少需要文本、角色或名称中的一项。 当同时提供文本和名称时，名称优先。

常见用例

填写一个网页表单

• 拨打 mcp_browser_navigate 电话打开目标页面。
• 打电话 mcp_browser_wait_for 等待表格加载。
• 通过CSS选择器呼叫 mcp_browser_type 填入每个字段。
• 请致电 mcp_browser_click 提交表格。
• 打电话 mcp_browser_wait_for 等待确认程序。
• 请致电 mcp_browser_get_text 查看并核实结果。

自动化桌面应用

• 打电话 mcp_desktop_activate_window 将应用推到前台。
• 呼叫 mcp_desktop_take_screenshot 以捕捉当前状态。
• 请拨打 mcp_accessibility_find_ui_element 电话按姓名查找按钮或字段。
• 呼叫 mcp_desktop_click 该元素报告的坐标。
• 呼叫 mcp_desktop_type_text 输入数据。
• 呼叫 mcp_desktop_press_keys 快捷键（例如，[“ctrl”，“s”]来保存）。
• 打电话 mcp_desktop_take_screenshot 确认结果。

从网页中提取数据

• 拨打 mcp_browser_navigate 电话打开页面。
• 调用 mcp_browser_get_text 提取可见文本内容。
• 调用 mcp_desktop_execute_python_code 解析并处理提取的数据。
• 当文本提取不够时，调用 mcp_browser_eval_js 通过JavaScript查询特定值。

运行开发任务

• 调用 mcp_desktop_execute_shell_command 、 git pullnpm install和 dotnet build。
• 调用 mcp_desktop_take_screenshot 捕获构建输出。
• 打电话 mcp_desktop_execute_python_code 分析日志或测试结果。
• 在浏览器中调用 mcp_browser_navigate 本地开发服务器。
• 呼叫 mcp_browser_screenshot 捕获渲染页面。

读写文件

• 用 mcp_desktop_execute_shell_commandtype C:\path\to\file.txt。
• 用Python的mcp_desktop_execute_python_code和open(...)写一个带有write(...)的文件。
• 请使用.mcp_desktop_execute_shell_command验证dir C:\path\to\output.txt。

带无障碍的复杂界面导航

• 打电话 mcp_accessibility_get_accessibility_tree 了解完整的用户界面结构。
• 调用 mcp_accessibility_find_ui_element 以查找特定控件（例如，角色：“MenuItem”，名称：“Settings”）。
• 用该元素报告的坐标呼叫 mcp_desktop_click 。
• 再次呼叫 mcp_accessibility_find_ui_element 以找到对话框中的下一个控制点。
• 打电话 mcp_desktop_type_text 或 mcp_desktop_click 与它互动。

保持一场长时间的游戏

• 每30分钟至少发送一次MCP请求，以防止闲置驱逐。
• mcp_desktop_get_screen_size 轻便且作为心跳音使用良好。