Windows-MCP 完全指南：用 MCP 协议让 AI Agent 原生操控 Windows 桌面

原创2026-10-13 19:36:351,914 阅读

文章标签：MCP 服务GUI 自动化AI 应用

Windows-MCP 完全指南：用 MCP 协议让 AI Agent 原生操控 Windows 桌面

本文围绕开源仓库 Windows-MCP 的官方 README 展开，系统讲解这一轻量级 MCP（Model Context Protocol）服务器如何在 Windows 上为 LLM Agent 提供文件导航、应用控制、UI 交互、QA 测试等能力。你将掌握从零安装、三种传输方式选型、Claude Desktop / Claude Code / Gemini CLI 等主流客户端接入、远程访问的完整安全配置（认证、IP 白名单、TLS、OAuth、SSRF 防护）、全量环境变量调优，以及 21 个 MCP 工具的参数细节与 DOM 浏览器自动化模式。文末附有源码级佐证，方便按图索骥深入仓库。

项目定位：为 LLM 与 Windows 之间架一座桥

Windows-MCP 是一个轻量级开源项目，核心目标是实现 AI Agent 与 Windows 操作系统之间的无缝集成。它本身作为 MCP Server 运行，位于 LLM 与操作系统中间：Agent 通过标准 MCP 协议调用服务器暴露的工具，服务器借助 Windows 原生 UI 自动化能力（UIA / IAccessible2）执行点击、输入、窗口管理、文件操作、注册表读写等真实桌面操作。pyproject.toml 中声明其包名为 windows-mcp，描述为 "Lightweight MCP Server for interacting with Windows Operating System"，mcp-name 为 io.github.CursorTouch/Windows-MCP，当前版本 0.8.7。

与许多依赖传统计算机视觉技术或专门微调模型的自动化工具不同，Windows-MCP 不依赖任何 CV 方案，任何 LLM 均可直接使用，从而大幅降低复杂度与搭建时间。据项目 README 介绍，它已加入 MCP Registry，并可通过 PyPI 分发（支持 uvx windows-mcp）。

典型操作延迟：动作与动作之间（例如一次鼠标点击到下一次点击）通常在 0.2～0.5 秒，具体取决于活跃应用数量、系统负载以及 LLM 的推理速度。

支持的操作系统（以 README 声明为准）：Windows 7 / 8 / 8.1 / 10 / 11。注意当前仓库 pyproject.toml 中 requires-python = ">=3.14"，README 前置条件则写 Python 3.13+，安装时请以实际发布版本的声明为准。

核心特性概览

原生 Windows 集成：直接与 Windows UI 元素交互，可打开应用、控制窗口、模拟用户输入等；
任意 LLM（视觉可选）：无需传统 CV 技术或特化模型，降低复杂度和配置成本；
丰富的 UI 自动化工具集：涵盖基础键盘/鼠标操作以及窗口/UI 状态采集；
轻量且开源：依赖精简、安装快捷，MIT 许可，源码完全开放；
可定制、可扩展：可方便地调整或扩展工具以适配特定自动化或 AI 集成需求；
实时交互：如上文所述，动作间延迟通常在 0.2～0.5 秒；
浏览器 DOM 模式：Snapshot 工具支持 use_dom=True 特殊模式，专注网页内容、过滤浏览器 UI 元素，支持 Chrome、Edge、Firefox（Firefox 因不通过 UIA 暴露 RootWebArea，采用 IAccessible2 回退）。

安装与前置条件

环境要求

Python 3.13+（当前仓库 pyproject.toml 实际声明 >=3.14）；
UV 包管理器：pip install uv 即可安装；
语言环境建议：Windows 默认语言尽量为英语，否则对于其他语言系统，建议禁用 MCP Server 中的 App 工具（README 给出的建议）。

提示：首次安装 MCP Server 时，因安装 pyproject.toml 中的依赖可能需要一两分钟，首次运行时服务器可能超时，可忽略并重启。

三种快速启动方式

# 默认 stdio 传输，直接运行
uvx windows-mcp serve

# 以 SSE 传输暴露到网络
uvx windows-mcp serve --transport sse --host localhost --port 8000

# 以 Streamable HTTP 传输暴露到网络（生产环境推荐）
uvx windows-mcp serve --transport streamable-http --host localhost --port 8000

源码安装方式：git clone https://gitcode.com/gh_mirrors/wi/Windows-MCP 后在仓库目录内以 uv --directory <路径> run windows-mcp serve 启动（用于客户端配置，见下文）。

开机自启（后台服务）

通过 Windows 计划任务将服务器注册为"登录即启动"的后台任务：

windows-mcp install

# 或显式指定 HTTP 传输与绑定地址
windows-mcp install --transport sse --host 127.0.0.1 --port 8000

该命令会创建一个名为 windows-mcp-server 的每用户计划任务，并在 ~/.windows-mcp/start-server.cmd 生成包装脚本；日志写入 ~/.windows-mcp/server.log 与 ~/.windows-mcp/server.error.log。执行 windows-mcp uninstall 即可移除。

从源码实现看，install/uninstall 命令通过 schtasks 查询与 Register-ScheduledTask -RunLevel Limited 注册 ONLOGON 触发任务（非提权环境即可注册），并用 subprocess.list2cmdline 生成包装脚本，将 stdout/stderr 分别重定向到日志文件。

传输方式选型

传输方式	命令	适用场景
`stdio`（默认）	`serve --transport stdio`	直接连接 Claude Desktop、Cursor 等 MCP 客户端
`sse`	`serve --transport sse --host HOST --port PORT`	通过 Server-Sent Events 提供网络访问
`streamable-http`	`serve --transport streamable-http --host HOST --port PORT`	通过 HTTP 流式传输提供网络访问（生产环境推荐）

stdio 为本地单会话模式；sse 与 streamable-http 均为网络可达模式，需要在启动时显式提供 --host 与 --port（默认 localhost:8000）。三种取值在 Transport 枚举中定义，serve 命令默认 stdio。

接入主流 MCP 客户端

Claude Desktop（claude_desktop_config.json）

方案 A：从 PyPI 安装（推荐）

{
  "mcpServers": {
    "windows-mcp": {
      "command": "uvx",
      "args": ["windows-mcp", "serve"]
    }
  }
}

方案 B：从源码安装

{
  "mcpServers": {
    "windows-mcp": {
      "command": "uv",
      "args": ["--directory", "<path to the windows-mcp directory>", "run", "windows-mcp", "serve"]
    }
  }
}

保存后完全重启 Claude Desktop，在 MCP 工具列表中确认服务器出现。

Claude Desktop MSIX（微软商店版）特殊说明：MSIX 打包版会虚拟化 %APPDATA%，导致两个问题：

配置文件位于 %LOCALAPPDATA%\Packages\Claude_pzs8srxjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json（而非 %APPDATA%\Claude\）；
从 "Claude Directory" 自动安装会失败，因为 ${__dirname} 变量解析到了错误的（非虚拟化）路径。

MSIX 沙箱中的 Electron 应用不会继承系统 PATH，因此必须使用 uvx.exe（或 uv.exe）的完整绝对路径：

方案 A：使用预装可执行文件：先执行 uv tool install windows-mcp，然后：

{
  "mcpServers": {
    "windows-mcp": {
      "command": "C:\\Users\\<user>\\.local\\bin\\windows-mcp.exe",
      "args": ["serve"]
    }
  }
}

方案 B：使用 uvx：

{
  "mcpServers": {
    "windows-mcp": {
      "command": "C:\\Users\\<user>\\.local\\bin\\uvx.exe",
      "args": ["windows-mcp", "serve"]
    }
  }
}

方案 C：从源码安装：

{
  "mcpServers": {
    "windows-mcp": {
      "command": "C:\\Users\\<user>\\.local\\bin\\uv.exe",
      "args": ["--directory", "C:\\path\\to\\Windows-MCP", "run", "windows-mcp", "serve"]
    }
  }
}

将 <user> 替换为你的 Windows 用户名，用 where uvx、where windows-mcp 或 where uv 确认真实路径；保存配置后通过托盘菜单完全退出并重新打开 Claude Desktop。

Perplexity Desktop

打开 Perplexity Desktop → Settings -> Connectors -> Add Connector -> Advanced；
名称填 Windows-MCP，粘贴以下任一配置。

从 PyPI（推荐）：

{
  "command": "uvx",
  "args": ["windows-mcp", "serve"]
}

从源码：

{
  "command": "uv",
  "args": ["--directory", "<path to the windows-mcp directory>", "run", "windows-mcp", "serve"]
}

保存后按需重启 Perplexity Desktop。

Gemini CLI

安装 @google/gemini-cli；
打开 %USERPROFILE%/.gemini/settings.json；
添加 windows-mcp 配置：

{
  "theme": "Default",
  "...": "...",
  "mcpServers": {
    "windows-mcp": {
      "command": "uvx",
      "args": ["windows-mcp", "serve"]
    }
  }
}

从源码运行：把 command 换成 uv，args 换成 ["--directory", "<path>", "run", "windows-mcp", "serve"]。

重启 Gemini CLI。

Qwen Code

安装 @qwen-code/qwen-code@latest；
打开 %USERPROFILE%/.qwen/settings.json；
添加配置（同上结构，command 为 uvx / uv），重启生效。

Codex CLI

安装 @openai/codex；
打开 %USERPROFILE%/.codex/config.toml；
添加：

[mcp_servers.windows-mcp]
command="uvx"
args=[
  "windows-mcp",
  "serve"
]

重启 Codex CLI。

Autohand Code

在 Windows 终端直接注册 stdio 服务器：

autohand mcp add windows-mcp uvx windows-mcp serve

在 add 后加 --scope project 可将服务器配置保留在当前项目中。

Claude Code（terminal）

方案 A：从 PyPI（推荐）：

claude mcp add --transport stdio windows-mcp -- uvx windows-mcp serve

方案 B：从源码：

claude mcp add --transport stdio windows-mcp -- uv --directory "<path>" run windows-mcp serve

让服务器对所有项目可用，追加 --scope user。用 claude mcp list 验证注册；在 Claude Code 内用 /mcp 查看服务器状态。若遇到 "Connection closed" 错误，使用 uvx.exe 完整路径：

claude mcp add --transport stdio windows-mcp -- C:\Users\<user>\.local\bin\uvx.exe windows-mcp serve

WSL 场景：从 WSL 运行 Claude Code 时，MCP 服务器必须仍在 Windows 侧执行（UI 自动化需要 Windows API），用 powershell.exe 作为桥接命令：

在 Windows（PowerShell）安装 uv：irm https://astral.sh/uv/install.ps1 | iex；
在 WSL 终端注册：

claude mcp add windows-mcp --transport stdio -s user -- powershell.exe -Command "C:\Users\<user>\.local\bin\uvx.exe windows-mcp serve"

-s user 使服务器对所有项目可用；重启 Claude Code 后以 /mcp 验证。

安全与访问控制（远程访问必读）

远程（网络）访问时，建议同时启用认证与 TLS：

windows-mcp serve --transport sse --host 0.0.0.0 \
  --auth-key "your_secret_token" \
  --ip-allowlist "203.0.113.0/24" \
  --ssl-certfile cert.pem --ssl-keyfile key.pem

认证（Authentication）

windows-mcp serve --transport sse --host 0.0.0.0 --auth-key "your_token"

启用后所有请求都需要携带 Authorization: Bearer your_token 头。实现上，AuthKeyMiddleware 拦截除健康检查与 OAuth 公开端点外的全部路径，使用 secrets.compare_digest 做常数时间比较；/health、OAuth 元数据与授权端点列入公开路径白名单。

IP 白名单（IP Allowlist）

windows-mcp serve --auth-key "token" --ip-allowlist "203.0.113.0/24,198.51.100.5"

将入站连接限制在指定 CIDR 范围内，默认阻止私网/回环地址以外的访问。解析逻辑在 parse_ip_allowlist，支持单个 IP（自动补 /32 或 /128）与 CIDR 网段，IPv4/IPv6 均可；IPAllowlistMiddleware 对不在白名单内的客户端返回 403。

CORS 源（CORS Origins）

默认不发出任何 CORS 头，浏览器会基于同源策略阻止跨域请求——即使服务器绑定在 localhost 上，任意网站也无法触达 MCP 控制面；同时还会根据绑定地址自动应用 Host 头校验（DNS 重绑定防护）。若需要浏览器端 MCP 客户端访问，显式开启源白名单：

windows-mcp serve --cors-origins "https://my-client.example.com,https://other.example.com"

仅列出的源会收到 Access-Control-Allow-Origin 头，其余跨域请求被浏览器拒绝。对应环境变量为 WINDOWS_MCP_CORS_ORIGINS。OptionsMiddleware 对 OPTIONS 预检请求仅在 Origin 命中白名单时回 CORS 头。

工具白名单（Tool Selection）

默认启用全部工具。用 --tools 只保留指定工具，或 --exclude-tools 屏蔽特定工具：

windows-mcp serve --tools "Screenshot,Click,Snapshot"   # 仅启用这三个
windows-mcp serve --exclude-tools "PowerShell,Registry" # 屏蔽特定工具

注意：ControlStatus 工具始终保留、不可被过滤移除（见 main.py 中 _apply_tool_filter）。

TLS / HTTPS

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

windows-mcp serve --ssl-certfile cert.pem --ssl-keyfile key.pem

--ssl-certfile 与 --ssl-keyfile 必须成对提供，否则启动报错。证书/密钥路径会注入 uvicorn 配置，服务器以 HTTPS 对外服务。

OAuth 2.0 + PKCE

面向使用 OAuth 而非静态 API Key 的 MCP 客户端（如 Claude Desktop）：

windows-mcp serve --transport streamable-http --host 0.0.0.0 \
  --ssl-certfile ~/.windows-mcp/cert.pem \
  --ssl-keyfile  ~/.windows-mcp/key.pem \
  --oauth-client-id my-client \
  --oauth-client-secret my-secret

Claude Desktop 配置：

{
  "mcpServers": {
    "windows-mcp": {
      "type": "http",
      "url": "https://<host>:8000/mcp/",
      "oauth": {
        "clientId": "my-client",
        "clientSecret": "my-secret"
      }
    }
  }
}

OAuth 服务器暴露的端点：

GET /.well-known/oauth-authorization-server — 服务器元数据（RFC 8414）；
GET /oauth/authorize — 授权码 + PKCE（强制 S256）；
POST /oauth/token — 令牌交换（需客户端密钥）；
POST /oauth/register — 禁用，客户端必须预先配置（预置型）。

动态客户端注册被关闭；重定向 URI 仅允许 loopback 的 http(s)。Auth Key 与 OAuth 可共存，二者都会被接受为合法 Bearer 令牌。源码中，serve 命令会校验二者必须成对出现，并通过 build_oauth_routes 挂载 OAuth 路由、构造 token 校验器供中间件使用。

配置文件 `~/.windows-mcp/config.toml`

不必每次敲一堆参数，可把配置写入 ~/.windows-mcp/config.toml。CLI 参数永远优先于配置文件。

搜索顺序：

--config /path/to/config.toml
~/.windows-mcp/config.toml

stdio（纯本地，无需安全配置）：

[server]
transport = "stdio"

SSE（网络访问 + 认证 + IP 限制）：

[server]
transport = "sse"
host      = "0.0.0.0"
port      = 8000
auth_key  = "your-secret-key"

[security]
ip_allowlist = ["192.168.1.0/24"]

Streamable HTTP（认证 + TLS + 工具排除）：

[server]
transport    = "streamable-http"
host         = "0.0.0.0"
port         = 8000
auth_key     = "your-secret-key"
ssl_certfile = "cert.pem"   # 相对 ~/.windows-mcp/ 解析
ssl_keyfile  = "key.pem"

[security]
ip_allowlist        = ["192.168.1.0/24"]
cors_origins        = ["https://my-client.example.com"]   # 可选 — 浏览器 CORS 开关
oauth_client_id     = "my-client"      # 可选 — 启用 OAuth 2.0 + PKCE
oauth_client_secret = "my-secret"

[tools]
exclude = ["PowerShell", "Registry"]   # 禁用特定工具

将证书和密钥放在同一目录：

~/.windows-mcp/
├── config.toml
├── cert.pem
└── key.pem

直接在该目录生成自签名证书：

mkdir -p ~/.windows-mcp
openssl req -x509 -newkey rsa:4096 \
  -keyout ~/.windows-mcp/key.pem \
  -out ~/.windows-mcp/cert.pem \
  -days 365 -nodes

从实现看，load_config 使用严格类型校验解析 TOML：server.transport 必须是 stdio/sse/streamable-http 三者之一，server.port 必须为 0–65535 整数，证书/密钥相对路径会解析为绝对路径；配置结构由 WindowsMCPConfig 等 dataclass 定义，默认传输为 stdio、默认主机 localhost、默认端口 8000。另有一个 [control] 段可调 mouse_takeover_units / mouse_takeover_pixels（合法范围 40–2000，控制用户接管阈值）。

`auth` 辅助命令

一键生成认证 Key 并写入可用的 ~/.windows-mcp/config.toml：

windows-mcp auth

同时生成认证与自签名 TLS 证书：

windows-mcp auth --transport streamable-http --host 0.0.0.0 --port 8000 --with-tls

该命令将 auth key 写入配置文件、可生成 cert.pem / key.pem，并按所选传输打印示例 MCP 客户端配置。实现上（auth 命令）用 secrets.token_urlsafe(32) 生成令牌；生成证书时优先探测 mkcert（本地可信证书，Windows 自动信任），未找到则回退 openssl 自签名并给出 Import-Certificate 信任指引。stdout 编码无法表示 ─ 时自动回退 ASCII 分隔线，避免 cp1252 控制台崩溃。

SSRF 防护

Scrape 工具会拦截：私网 IP、回环地址、链路本地地址、URL 内嵌凭据、非 HTTP 协议。底层 validate_url 对域名做一次 DNS 解析并校验所有解析地址，safe_get 通过 _PinnedIPAdapter 将连接固定到已校验地址，杜绝"解析后翻转"的二次劫持窗口；重定向由调用方逐跳重新校验，不自动跟随。

远程绑定的强制校验

从 serve 命令可看到一条硬性安全规则：当 HTTP 传输绑定到非回环地址且未配置 auth_key、OAuth，也未显式传 --allow-insecure-remote 时，服务器拒绝启动。同时根据绑定地址自动计算允许的 Host 头列表（回环绑定放行 localhost/127.0.0.1/[::1]），实现 DNS 重绑定防护；--auth-key / --ip-allowlist 对 stdio 传输无效（会告警）。

环境变量全景

所有变量均可选（除非另有说明），通过 claude_desktop_config.json 的 env 键（或对应客户端配置）设置。

截图与快照

变量	默认值	说明
`WINDOWS_MCP_SCREENSHOT_SCALE`	`1.0`	截图编码前的缩放系数，接受 `0.1`–`1.0` 浮点数。在高分辨率（1440p、4K）下默认尺寸可能超过 Claude Desktop 的 1 MB 工具结果上限，设为 `0.5` 可让宽高各减半（文件大小约 1/4）。实现见 _snapshot_helpers.py 的 _screenshot_scale，越界值自动钳制
`WINDOWS_MCP_SCREENSHOT_BACKEND`	`auto`	截图采集后端：`auto`（按 dxcam → mss → pillow 顺序尝试）、`dxcam`、`mss`、`pillow`。dxcam 不可用或 GPU 异常时改用 `mss` 或 `pillow`。实现见 desktop/screenshot.py
`WINDOWS_MCP_PROFILE_SNAPSHOT`	关闭	设为 `1`/`true`/`yes`/`on` 时，输出 Screenshot/Snapshot 各阶段耗时日志，用于诊断慢截图
`WINDOWS_MCP_DISABLE_FLASH`	关闭	设为 `1`/`true`/`yes`/`on` 时，取消每次截图后短暂出现的橙红色发光边框。该边框渲染在透明的置顶窗口上（截图之后），因此永远不会出现在截图像素中

安全

变量	默认值	说明
`WINDOWS_MCP_AUTH_KEY`	无	所有 HTTP 请求所需的 Bearer 令牌，等价于 `--auth-key`
`WINDOWS_MCP_IP_ALLOWLIST`	无	逗号分隔的客户端 IP/CIDR 列表（如 `203.0.113.0/24,198.51.100.5`），等价于 `--ip-allowlist`
`WINDOWS_MCP_CORS_ORIGINS`	无	允许跨域浏览器请求的源列表（逗号分隔）；未设置时不发出任何 CORS 头。等价于 `--cors-origins`
`WINDOWS_MCP_TOOLS`	全部启用	显式启用的工具列表（如 `Screenshot,Click,Snapshot`），等价于 `--tools`
`WINDOWS_MCP_EXCLUDE_TOOLS`	无	禁用的工具列表（如 `PowerShell,Registry`），等价于 `--exclude-tools`
`WINDOWS_MCP_SSL_CERTFILE`	无	TLS 证书文件路径（.pem），必须与 `WINDOWS_MCP_SSL_KEYFILE` 成对
`WINDOWS_MCP_SSL_KEYFILE`	无	TLS 私钥文件路径（.pem），必须与 `WINDOWS_MCP_SSL_CERTFILE` 成对
`WINDOWS_MCP_OAUTH_CLIENT_ID`	无	HTTP 传输的 OAuth 客户端 ID，必须与 `WINDOWS_MCP_OAUTH_CLIENT_SECRET` 成对
`WINDOWS_MCP_OAUTH_CLIENT_SECRET`	无	HTTP 传输的 OAuth 客户端密钥，必须与 `WINDOWS_MCP_OAUTH_CLIENT_ID` 成对
`WINDOWS_MCP_STATELESS_HTTP`	`false`	设为 `1`/`true`/`yes`/`on` 时，`streamable-http` 不再使用 `Mcp-Session-Id` 连接状态，适合服务重启后的重连以及水平扩展部署

遥测

变量	默认值	说明
`ANONYMIZED_TELEMETRY`	`true`	设为 `false` 关闭匿名使用遥测；无论设置如何，绝不收集个人数据、工具参数或输出
`POSTHOG_API_KEY`	项目默认	覆盖匿名遥测使用的 PostHog 项目写入 Key；设为空字符串跳过 PostHog 客户端初始化
`POSTHOG_HOST`	`https://us.i.posthog.com`	覆盖遥测 PostHog 主机（如自建 PostHog）

调试

变量	默认值	说明
`WINDOWS_MCP_DEBUG`	`false`	设为 `1`/`true`/`yes`/`on` 启用调试模式（日志级别提到 DEBUG），等价于 `--debug` 标志

看门狗（WatchDog）

变量	默认值	说明
`WINDOWS_MCP_WATCHDOG`	`false`	设为 `on`/`1`/`true`/`yes`/`enabled`（大小写不敏感）时运行 UIA 焦点看门狗。默认关闭：它目前唯一的剩余作用是焦点变更的调试日志，却要付出一个后台线程和长生命周期 UIA 事件订阅的代价，后者在长时间运行（如睡眠/恢复、会话切换）后可能使服务器在 UIA 不稳定环境中崩溃。无障碍树每次工具调用都按需构建，因此关闭它不影响任何工具行为。相关逻辑见 _watchdog_enabled

本地配置示例（claude_desktop_config.json）：

{
  "mcpServers": {
    "windows-mcp": {
      "command": "uvx",
      "args": ["windows-mcp", "serve"],
      "env": { "WINDOWS_MCP_SCREENSHOT_SCALE": "0.5" }
    }
  }
}

远程配置示例（认证 + IP 白名单 + TLS）：

{
  "mcpServers": {
    "windows-mcp": {
      "command": "uvx",
      "args": ["windows-mcp", "serve", "--transport", "sse", "--host", "0.0.0.0"],
      "env": {
        "WINDOWS_MCP_AUTH_KEY": "your_token",
        "WINDOWS_MCP_IP_ALLOWLIST": "203.0.113.0/24",
        "WINDOWS_MCP_SSL_CERTFILE": "/path/to/cert.pem",
        "WINDOWS_MCP_SSL_KEYFILE": "/path/to/key.pem"
      }
    }
  }
}

MCP 工具集详解

MCP 客户端可通过以下 21 个工具与 Windows 交互。它们由 tools 子包的 register_all 统一注册到 FastMCP 实例上，按功能可分为感知、输入、应用/浏览器、系统与批量五类。

桌面感知类

Screenshot：快速"截图优先"桌面采集，返回光标位置、活动/已打开窗口摘要与图像。为速度跳过 UI 树提取，在主要需要视觉上下文时应作为默认首调。支持 display=<a href="https://link.gitcode.com/i/1d8d05f7bcc283b0b40536f3f6f802db" target="_blank">0] 或 display=[0,1]（零基的活动 Windows 显示器索引）与 region=[left, top, right, bottom]（虚拟桌面像素坐标，只截取该矩形，更省 token）；两者同时给出时 region 优先，非法或越界 region 会报错而非静默截取其他区域。采集完成后在捕获区域内绘制短暂橙红色发光边框作为视觉确认（可用 WINDOWS_MCP_DISABLE_FLASH=1 关闭）。注意：返回图像可能被降采样，缩放后需用"原始尺寸/显示尺寸"比例换算坐标再交给 Click、Move 等工具（元数据中会给出 Screenshot Coordinate Scale 提示）。实现见 [tools/snapshot.py 的 _screenshot_tool。
Snapshot：完整桌面状态采集，适合需要交互元素 id、可滚动区域或 use_dom=True 浏览器提取的工作流。支持 use_vision=True（附带截图）、use_annotation=False（不带 UI 元素包围框的干净截图）、use_ui_tree=False（更快地仅截图）、width_reference_line / height_reference_line（叠加参考网格改善空间推理，需配合视觉）、use_dom=True（浏览器内容提取网页元素而非浏览器 UI）、display=<a href="https://link.gitcode.com/i/14699de8049fabd5938354f24148cf29" target="_blank">...] 与 region=[...]（规则同 Screenshot）。官方建议：行动前先调用它理解桌面当前状态。返回内容包含系统语言、聚焦/已打开窗口、交互元素（按钮、文本框、链接、菜单及坐标）、可滚动区域与语义树，并做了 Unicode 私用区字符清理与代理对修复（见 [build_snapshot_response）。
DisplayInventory：读取显示器布局、工作区、有效 DPI 与缩放元数据。
ControlStatus：读取桌面控制权属主与剩余用户空闲等待。用户接管（takeover）阻塞新工具调用时它仍然可用。AI 控制期间可见边缘与光标辉光指示器，物理鼠标大幅移动或按下 Ctrl+Alt+Shift+Backspace 可交还控制权，直到空闲 10 秒后 AI 重新接管。截图采集期间指示器暂时隐藏、物理输入暂时释放；此窗口内的任何物理输入会抢占 AI 控制（ControlStatus 可能短暂仍报 ai，直至事件被处理）。分步桌面输入会在下一检查点停止，但已在运行的外部命令（如 PowerShell、App 启动）可能继续执行——该控制门不会取消进程或回滚已完成的副作用。检测到钩子故障时注入的按键/鼠标按钮会被异步释放，物理输入可能短暂与仍按住的 AI 键重叠；Windows 也可能静默移除低级钩子，周期性钩子替换只能降低这种风险。用户接管属于尽力而为，不是安全边界或独占控制保证。无会话 MCP 客户端（2026-07-28 之后的会话无关客户端）无法收到主动推送的控制状态日志，需要时应主动查询 ControlStatus。

输入操作类

Click：在给定坐标 [x, y] 点击，或传 UI 元素 label/id。button 支持 left（选择/激活）、right（右键菜单）、middle；clicks 支持 0（仅悬停不点击）、1（单击选中/聚焦）、2（双击打开/激活）。loc 与 label 必须提供其一。
Type：在坐标或元素上输入文本。clear=True 先清空现有文本（默认追加）；press_enter=True 输入后回车提交；caret_position 支持 start（开头）/ end（末尾）/ idle（默认）。空文本不输入任何内容，可配合 clear=True 仅清空字段。clear 与 press_enter 只接受 true/false。
Scroll：在坐标、元素 label 或当前鼠标位置（loc=None）滚动。type：vertical（默认）/horizontal；direction：垂直 up/down、水平 left/right；wheel_times 控制幅度（1 格约 3–5 行）。适合长内容、列表与网页导航。
Move：移动鼠标到坐标或元素。drag=True 从当前位置拖拽到目标；确定性拖拽：drag=True + from_loc=[x, y] 可在一个调用内显式指定起点按下并释放到 loc；可选 duration 增加有界中间移动（from_loc 与 duration 必须配合 drag=True）。
Shortcut：发送键盘组合键，如 ctrl+c、ctrl+v、alt+tab、win+r（运行框）、win（开始菜单）、ctrl+shift+esc（任务管理器）。底层键名别名映射见 desktop/service.py 的 _KEY_ALIASES。
Wait：按秒暂停，适合等待应用启动/加载、UI 动画、页面渲染、对话框出现或快速动作之间的间隔。
WaitFor：在一个调用内轮询 UI 状态直到条件满足，避免反复调用 Snapshot。条件：text_exists、active_window、element_exists、element_enabled、focused_element（也接受别名 text/window/element/enabled/focused），按条件提供 text 和/或 window_name；use_dom=True 可匹配浏览器 DOM 文本。timeout 默认 10 秒、上限 120 秒；interval 默认 0.25 秒、上限 5 秒（参数校验见 input.py 的 _validate_wait_for_args）。匹配逻辑在单次工具调用内对无障碍树轮询（input.py 的 _matches_wait_condition）。

应用与浏览器类

App：启动与管理应用窗口，四种模式（见 tools/app.py）：
- launch：按开始菜单名称打开应用；
- launch_executable：严格按可执行文件路径启动，argv 分离传入并支持可选 cwd（executable/args/cwd 仅此模式可用，路径不存在会报错，以 shell=False 启动避免注入）；
- resize：调整指定或活动窗口大小；
- switch：将特定窗口带到前台。
Scrape：抓取整个网页信息。默认（use_dom=False）对 URL 发轻量 HTTP 请求，返回经过 LLM 清洗的页面摘要以避免上下文膨胀，可用 query 聚焦特定信息；use_dom=True 改为从活动浏览器标签的 DOM 提取（站点屏蔽 HTTP 请求时必需，支持 Chrome/Edge/Firefox）；use_sampling=False 返回未经 LLM 处理的原始内容。DOM 提取时还会附带"已到顶部/继续下滑查看"的滚动状态提示（见 tools/scrape.py）。

系统操作类

PowerShell：执行 PowerShell 命令。
FileSystem：文件与目录的读、写、复制、移动、删除、列出、搜索、信息查看，八种模式：read（可选行 offset/limit 与 encoding）、write（append=True 追加）、copy、move、delete（recursive=True 删非空目录）、list（pattern 过滤、show_hidden）、search（glob 模式）、info（大小、日期、类型等元数据）。相对路径从用户桌面目录解析，访问其他位置需用绝对路径（见 tools/filesystem.py）。
Process：列出运行进程，或按 PID/名称终止。
Registry：Windows 注册表值的读、写、删、列：get / set（type 支持 String 等注册表类型）/ delete / list。路径使用 PowerShell 格式，如 HKCU:\Software\MyApp、HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion（见 tools/registry.py）。
Clipboard：读取或设置 Windows 剪贴板内容。
Notification：发送带标题和消息的 Windows Toast 通知。

批量操作类

MultiSelect：批量选中多个项目（文件、文件夹、复选框），支持可选 Ctrl 键；提供 label 时使用批量 label→坐标解析。
MultiEdit：在指定坐标的多个输入框中输入文本；提供 label 时使用批量 label→坐标解析。

DOM 模式与浏览器自动化

Snapshot 工具的 use_dom=True 是浏览器自动化的关键开关：它只关注网页内容，过滤掉浏览器 UI 元素，输出更干净、更高效的网页元素信息。支持 Chrome、Edge 和 Firefox：

Chrome / Edge 通过 UIA 暴露 AutomationId == "RootWebArea" 作为 DOM 模式入口标记；
Firefox 不通过 UIA 暴露 RootWebArea，因此走 IAccessible2（MSAA/IA2）回退——tree/ia2.py 专门实现从 Firefox 窗口句柄获取根 IAccessible 的遍历，输出 dom_informative_nodes、dom_interactive_nodes 与 dom_bounding_box，并过滤非活动标签页与浏览器 chrome（工具栏、标签条、地址栏、书签）以免淹没结果。树构建在 tree/service.py 的 get_state 中完成，dom_is_ia2 标记 Firefox 路径。DOM 树遵循遍历上限，防止重型页面下无障碍树过大。

配套的 Scrape 工具 use_dom=True 模式与 WaitFor 的 use_dom=True 均复用同一 DOM 提取能力。

遥测与数据隐私

Windows-MCP 会收集使用数据以帮助改进服务器，但不追踪任何个人信息、工具参数或输出。禁用方法——在 MCP 客户端配置中设置：

{
  "mcpServers": {
    "windows-mcp": {
      "command": "uvx",
      "args": ["windows-mcp", "serve"],
      "env": { "ANONYMIZED_TELEMETRY": "false" }
    }
  }
}

启动逻辑中（main.py 的 lifespan）仅在 ANONYMIZED_TELEMETRY 未显式设为 false 时才初始化 PostHogAnalytics。更多数据收集与处理细节见 SECURITY.md 的遥测与数据隐私章节。

已知局限

无法选取段落中的特定文本区域（依赖 a11y 树），官方正在解决；
Type 工具面向输入文本，不适用于在 IDE 中编程（会把程序整体键入文件），官方正在解决；
本 MCP 服务器不能用来玩视频游戏。

安全总则与更多资料

Windows-MCP 以完全系统访问权限运行，可执行不可逆操作，部署前务必通读 SECURITY.md，其中包含工具级风险评估、部署建议、漏洞报告流程与合规审计指引。贡献与开发环境搭建参见 CONTRIBUTING.md，项目采用 MIT 许可，依赖的核心开源库为 Python-UIAutomation-for-Windows（UIAutomation）。pyproject.toml 中还声明了项目脚本入口 windows-mcp = "windows_mcp.__main__:main"（即上文所有 windows-mcp serve / install / uninstall / auth 命令的来源），运行时依赖包括 fastmcp、pywin32、comtypes、dxcam、pillow、thefuzz、posthog 等。

提示：CLI 现已升级为命令组结构，旧式顶层传参（如 windows-mcp --transport sse）会被引导改用 windows-mcp serve --transport sse，详见 _LegacyAwareGroup 的提示逻辑。

登录后查看全文

MCP 服务GUI 自动化AI 应用

Windows-MCP

Windows-MCP 完全指南：用 MCP 协议让 AI Agent 原生操控 Windows 桌面

Windows-MCP 完全指南：用 MCP 协议让 AI Agent 原生操控 Windows 桌面

项目定位：为 LLM 与 Windows 之间架一座桥

核心特性概览

安装与前置条件

环境要求

三种快速启动方式

开机自启（后台服务）

传输方式选型

接入主流 MCP 客户端

Claude Desktop（claude_desktop_config.json）

Perplexity Desktop

Gemini CLI

Qwen Code

Codex CLI

Autohand Code

Claude Code（terminal）

安全与访问控制（远程访问必读）

认证（Authentication）

IP 白名单（IP Allowlist）

CORS 源（CORS Origins）

工具白名单（Tool Selection）

TLS / HTTPS

OAuth 2.0 + PKCE

配置文件 ~/.windows-mcp/config.toml

auth 辅助命令

SSRF 防护

远程绑定的强制校验

环境变量全景

截图与快照

安全

遥测

调试

看门狗（WatchDog）

MCP 工具集详解

桌面感知类

输入操作类

应用与浏览器类

系统操作类

批量操作类

DOM 模式与浏览器自动化

遥测与数据隐私

已知局限

安全总则与更多资料

相关推荐

热门文章

配置文件 `~/.windows-mcp/config.toml`

`auth` 辅助命令