win-mind

WinMind

一个 Windows MCP 服务，让 AI 能通过辅助功能树查看并操控任意应用——无需截图、无需鼠标、无需猜测像素坐标——还提供 200 多种原生 Windows 工具。

大多数计算机操作 Agent 都会查看屏幕：截取屏幕截图，向模型发送数千个图像令牌，猜测坐标，点击，再截取一张屏幕截图。WinMind 读取 Windows 已知的信息。每个应用都会通过 UI Automation（辅助功能层）公开按钮、文本框、列表和文本；屏幕阅读器 Narrator 和 NVDA 也会使用这一层。WinMind 将这些内容转换成精简的编号树，AI 可以在一次调用中读取，并在下一次调用中操作——即使应用被其他窗口遮挡也没问题。

WhatsApp  (WhatsApp.Root.exe, window)
├─ [6] banner
│  ├─ [7] button "Chats" (42) checked [toggle]
│  ├─ [8] button "Calls" (4) unchecked [toggle]
├─ [20] textbox "Search or start a new chat" [set_value]
├─ [21] tabs "chat-list-filters" (4)
│  ├─ [22] tab "All" selected [select]
│  ├─ [23] tab "Unread 42" [select]
├─ [26] grid "Chat list" (9)
│  ├─ [29] row "Alex Yesterday Photo" [click]
│  ├─ [30] row "Study Group 3 unread messages Yesterday" [click]
└─ [37] button "Send document" [click]

ui_act(ref=30) 可打开该聊天窗口。ui_act(name="Play", title_contains="spotify") 可播放音乐。整个过程没有截取屏幕截图。

与众不同之处

	截图 Agent	WinMind
模型获取的内容	图像（每张图像包含数千个令牌）	包含真实名称、状态和操作的文本树
每次查看的速度	数秒（截屏 + 视觉模型）	整个应用仅需 0.1-0.3 秒（一次跨进程调用）
点击方式	像素坐标，会移动鼠标	使用应用自身的辅助功能操作——鼠标完全不会移动
被其他窗口遮挡的应用	必须将窗口置于最前	可在后台读取和操作
编辑器/文档中的文本	OCR	应用提供的准确文本（TextPattern）

WinMind 能处理一些容易让简单 UI Automation 工具出错的情况（详情见 docs/ARCHITECTURE.md）：

• 被其他窗口遮挡的 Chromium 应用（Discord、Spotify、Steam、Teams、VS Code）在被遮挡时不会公开内容——Chromium 的遮挡跟踪会暂停这些应用。WinMind 会正确唤醒它们一次；之后即可在后台持续读取其树。它绝不会把窗口拉到全屏游戏前面。
• 托管 WebView2 的 WinUI 3 应用（WhatsApp）会循环访问自身的网页内容——简单的扫描会重复获取相同元素数千次。WinMind 会拆分并去重：7.3 秒 -> 0.25 秒。
• 点击网页后无声无息地不起作用：例如列表项的点击处理程序位于内部链接上。WinMind 会执行真正处理点击的元素的默认操作——无需移动鼠标。
• 同一棵树中同时包含按钮和文本：编辑器/文档内容会与控件一同提供。
• 按进程查找应用，而不只是按标题查找（Spotify 的标题是正在播放的歌曲），也包括隐藏在系统托盘中的应用。
• 令牌预算：222 个工具定义约占 32k 个令牌（每个工具 143 个）；过长的输出会被截断，并附上说明被截去内容的提示；错误信息是一行可执行的说明，而不是回溯信息。

包含的内容（222 个工具）

类别	示例
UI 自动化	ui_tree、ui_map、ui_act、ui_read、ui_find_text、ui_element_at、ui_focused
健康与诊断	full_health_scan、why_is_my_pc_slow、smart_disk_health、battery_health、reliability_records
硬件与游戏	CPU/GPU 指标、温度、风扇、FPS / 帧时间 / 卡顿 / GPU 瓶颈（PresentMon）
实时 OS 跟踪	ETW 进程 / DNS / 文件 / 网络事件
网络	why_no_internet、port_process_map、whats_on_port、DNS 缓存、Wi-Fi 扫描
隐私与安全	whats_using_my_webcam / _mic、Defender、BitLocker、USB 历史记录、启动项
Windows 与桌面	窗口、虚拟桌面、已保存的工作区
文件、进程、服务、注册表	防护措施可避免操作系统文件夹、关键项和核心 OS 进程
显示、音频、媒体、语音	单个应用音量、正在播放的媒体 + 媒体控制、亮度、夜间模式、TTS
屏幕捕获（仅限显式调用）	capture_window_image 即使窗口被遮挡，也能渲染该窗口

完整列表（每个工具占一行）：TOOLS.md。AI 也可以调用 tool_guide 获取分类索引。

快速开始

一键安装：Claude Desktop

从 Releases 下载 winmind-mcp-<version>.mcpb，然后 打开它 — Claude Desktop 会像安装浏览器扩展一样安装它（需要 uv，它会为你配置 Python 依赖项）。该安装包包含原生辅助程序。

任意 MCP 客户端（Claude Code、Cursor、VS Code、本地模型……）

要求：Windows 10/11、Python 3.10+。

git clone https://github.com/jhonpork1233-beep/win-mind
cd win-mind
pip install -e .

将其添加到 MCP 客户端。使用 Python 的完整路径，这样 PATH 发生变化时也不会导致运行失败：

// Claude Desktop / Claude Code (~/.claude.json "mcpServers") / any MCP client
{
  "winmind": {
    "command": "C:\\Path\\To\\Python\\python.exe",
    "args": ["-m", "winmind"]
  }
}

Claude Code 快捷方式：claude mcp add winmind -- "C:\Path\To\Python\python.exe" -m winmind

然后可以询问类似 “我的 WhatsApp 未读聊天中有什么？”、“在 Spotify 上播放我点赞的歌曲”、“我的 PC 为什么很慢？”、“不切换窗口，给记事本截图” 等问题。

可选原生辅助程序

核心功能（UI 引擎、文件、进程、注册表、健康、网络等）均为纯 Python。部分工具会使用小型原生 辅助程序 — 实时事件挂钩、ETW、窗口流式传输、虚拟桌面、WinRT 代理（媒体、通知）、HUD 叠加层、PresentMon。可在 native/ 中从源代码构建：

powershell -ExecutionPolicy Bypass -File scripts\build_all.ps1

（Visual Studio 2022 Build Tools，需安装 C++ 工作负载和 Windows SDK；构建 winmind_native.dll 需要 MinGW g++。）未构建辅助程序的工具会说明这一点，并告知要运行的脚本。

高效使用（面向 AI 客户端和提示词编写者）

• 从 ui_tree（结构）或 ui_read（仅文本）开始 — 不要使用屏幕截图。
• 名称明确时按名称操作：ui_act(name="Search", title_contains="spotify")；否则按 ref 操作。
• 优先使用摘要工具（full_health_scan、system_health_summary、windows_summary），而非原始列表 （appx_packages、service_list、port_process_map）。
• 每个工具都接受 detail=true（不进行截断）、compact=true（使用简短键名）。
• 使用延迟加载工具的客户端（例如 Claude Code 的工具搜索）只会加载所用工具的定义。

安全

WinMind 使用当前用户的权限运行，并且可以更改系统 — 这正是它的用途。请阅读 SECURITY.md。

• 每个工具都带有 MCP 风险注解（readOnlyHint、destructiveHint），客户端可以在执行高风险调用前征求确认； 其中 16 个工具标记为破坏性操作。
• 内置防护措施：文件工具拒绝操作 Windows/System32/Program Files 和驱动器根目录；注册表写入/删除操作拒绝处理 关键项；进程工具拒绝操作核心 OS 进程。
• UI 引擎绝不截图，也不会移动鼠标。屏幕捕获仅通过显式调用相应工具实现。
• 无遥测。WinMind 写入的所有内容都保存在 %LOCALAPPDATA%\WinMind 中（可通过 WINMIND_HOME 覆盖）。
• 除非需要仅限管理员使用的工具，否则请以非提权方式运行。

测试

pip install -e .[dev]
python tests\audit_tools.py tests\audit.json     # calls every safe tool, sandbox-tests the write tools
python tests\audit_summary.py tests\audit.json

审计仅写入临时文件夹、临时注册表项 HKCU\Software\WinMindAudit、由其自身启动的进程，以及其自身的记事本窗口。当前结果：109 个只读工具中有 102 个运行正常（其余工具需要管理员权限、正在运行的会话或已打开的 Office 文档），37 项沙箱和防护测试全部通过。

路线图

• Java Access Bridge（Java/Swing 应用）、Firefox/LibreOffice 的 IAccessible2 文本
• 稳定的选择器和录制的工作流
• 实时 UI 事件流（传递树结构差异，而非重新读取）
• UI Automation Remote Operations，实现更快的树结构获取
• 一键安装：Claude Desktop 扩展、Windows Agent 连接器（设备端注册表）
• 与其他 Windows MCP 服务进行公开的正面对比基准测试

许可证

Apache-2.0。第三方组件：THIRD_PARTY_NOTICES.md。