win-automation

name	win-automation
description	Control Windows applications via MCP - screenshots, UI automation, keyboard/mouse input

Windows Automation MCP Server

Windows 桌面自动化 MCP 服务器，提供截图、UI 自动化、键盘鼠标输入等功能。

功能列表

工具	功能
list_apps	列出正在运行的应用及其窗口
list_windows	列出所有可见窗口
get_window	通过 HWND 获取窗口信息
launch_app	启动应用
get_window_state	截图 + 无障碍树（带元素索引）
click	坐标点击或元素索引点击
type_text	输入文本（支持中文）
press_key	按键/快捷键
scroll	滚动
drag	拖拽
set_value	设置可编辑元素的值
perform_secondary_action	执行元素辅助操作
activate_window	将窗口带到前台

使用流程

1. 发现应用

list_apps() -> 获取所有运行中的应用和窗口

2. 获取窗口状态

get_window_state(hwnd=12345, include_screenshot=True, include_accessibility=True)

• 返回截图（PNG）和无障碍树
• 元素索引从 0 开始，深度优先遍历
• 索引是临时的，每次 get_window_state 会刷新

3. 交互操作

click(hwnd=12345, x=100, y=200)           # 坐标点击
click(hwnd=12345, index=5)                  # 元素点击
type_text(hwnd=12345, text="你好世界")       # 输入中文
press_key(hwnd=12345, keys="Control_L+c")   # 复制
scroll(hwnd=12345, x=500, y=300, scroll_y=-3)  # 向上滚动

坐标系统

• 所有坐标相对于窗口客户区（不含标题栏和边框）
• (0, 0) 是窗口客户区左上角
• 截图中的坐标与窗口坐标一致

元素索引

• 索引是临时的，仅在最近一次 get_window_state 调用后有效
• 如果操作失败提示索引无效，重新调用 get_window_state 刷新
• 某些应用（Electron、游戏）可能无障碍树为空，此时使用坐标操作

快捷键格式

使用 X11 keysym 风格名称，用 + 连接：

• Control_L+c → Ctrl+C
• Control_L+Shift_L+s → Ctrl+Shift+S
• Alt_L+F4 → Alt+F4
• Return → 回车
• Escape → ESC
• space → 空格

中文输入

type_text 通过剪贴板粘贴方式输入，完全支持 Unicode/中文字符。

截图

• 使用 PrintWindow API，支持被遮挡窗口
• 默认最大宽度 1280 像素，可通过 max_screenshot_width 参数调整
• 最小化窗口需要先 activate_window 恢复

错误处理

• 窗口不存在：返回 "Window {hwnd} no longer exists"
• 元素索引过期：返回 "Element index N not found"
• 权限不足：某些系统窗口可能无法操作

安装和配置

依赖

pip install mcp comtypes pillow pyautogui

Claude Code 配置

在 .claude/settings.local.json 中添加：

{
  "mcpServers": {
    "win-automation": {
      "command": "python",
      "args": ["path/to/win-automation-mcp/server.py"]
    }
  }
}

测试

python server.py  # 应该无输出（等待 stdio 输入）