peekaboowin 0.1.24

Windows 桌面自动化 MCP 服务器 - 让 AI 代理能看见和操作 Windows 桌面应用

PeekabooWin MCP

Windows 桌面自动化 MCP 服务器 — 让 AI 代理能看见和操作 Windows 桌面应用。

基于 Windows UI Automation (UIA) + SendInput + PaddleOCR，提供完整的桌面交互能力：元素发现、输入模拟、截图、窗口管理、剪贴板、OCR 识别。

---

系统要求

• 操作系统: Windows 10 或 Windows 11
• 工具: 推荐 uv（Python 包管理）
• 权限: 管理员身份运行可解锁所有功能（向提升权限窗口发送输入）
• OCR: 可选，需安装 PaddleOCR（约 1GB，依赖 C++ 编译器 — 安装 Microsoft C++ Build Tools 并勾选 "使用 C++ 的桌面开发" 工作负载）

---

安装

方式一：一键安装（推荐）

irm https://raw.githubusercontent.com/wangneal/PeekabooWin/main/install.ps1 | iex

脚本自动安装 uv 和 PeekabooWin，并直接从 GitHub 主分支安装最新代码；重复运行同一命令会强制更新。

方式二：安装到本地（推荐给客户机）

# 需要先安装 uv: https://docs.astral.sh/uv/#installation

# 普通版本：从 GitHub 安装/更新，避免 PyPI 版本滞后
uv tool install git+https://github.com/wangneal/PeekabooWin --upgrade --force

# 更新后验证
peekaboowin --version

如果需要 OCR，再执行：

uv tool install --python 3.12 git+https://github.com/wangneal/PeekabooWin --upgrade --force --with paddleocr --with "paddlepaddle>=2.6,<3.0"
peekaboowin-setup

peekaboowin-setup 会优先从本仓库 ocr-models Release 下载模型；Release 资源不存在时才回退到 PaddleOCR 官方地址。也可以通过 PEEKABOOWIN_OCR_MODEL_BASE_URL 指定企业内网镜像。

安装后可用 peekaboowin 命令直接启动，MCP 客户端也建议使用 peekaboowin 命令，而不是日常启动时使用 uvx --upgrade。

方式三：uvx 临时运行（不建议作为日常 MCP 配置）

uvx --upgrade --from git+https://github.com/wangneal/PeekabooWin peekaboowin

裸 uvx peekaboowin 会从 PyPI 拉取版本；如果 PyPI 还没同步新版本，客户机可能仍启动旧的 0.1.0。不要在 MCP 客户端启动配置里长期加 --upgrade，否则每次启动都可能因联网解析依赖而触发 32001 超时。

方式四：从源码安装

git clone https://github.com/wangneal/PeekabooWin.git
cd PeekabooWin
uv pip install -e ".[ocr]"

更新旧版本客户机

更新前请先关闭正在使用 PeekabooWin 的 MCP 客户端，或结束正在运行的 peekaboowin 进程。客户机如果运行 peekaboowin --version 后仍输出启动日志并显示 "version": "0.1.0"，说明当前仍是旧包；旧版不支持 --version，所以会直接启动 MCP 服务。

本地安装版（MCP 配置使用 peekaboowin 命令）

# 推荐：强制从 GitHub 主分支更新
uv tool install git+https://github.com/wangneal/PeekabooWin --upgrade --force

# 如果客户机安装了 OCR 扩展
uv tool install --python 3.12 git+https://github.com/wangneal/PeekabooWin --upgrade --force --with paddleocr --with "paddlepaddle>=2.6,<3.0"

# 更新后验证
peekaboowin --version

如果仍然显示 0.1.0，先卸载旧工具再重装：

uv tool uninstall peekaboowin
uv tool install git+https://github.com/wangneal/PeekabooWin --force
peekaboowin --version

uvx 运行版（MCP 配置使用 uvx）

如果客户机之前依赖裸 uvx peekaboowin，在 PyPI 未同步最新版本前建议改为本地安装版，并把 MCP 配置改成：

"command": "peekaboowin"

如需临时验证 GitHub 最新版，可在 PowerShell 单独执行：

uvx --upgrade --from git+https://github.com/wangneal/PeekabooWin peekaboowin --version

如果已经把 MCP 配置改成了 --upgrade，建议改回快速启动，避免客户端等待 uv 联网解析时出现 32001 超时。

如果首次就超时

通常有两种原因：

1. 客户端启动配置里还在做 uvx --upgrade，导致每次启动都要联网解析依赖。
2. 客户端仍从 PyPI/旧缓存启动 0.1.0，没有使用 GitHub 最新版。
3. 机器安装的是 OCR 版本，但还没有预下载模型，首次 OCR 会触发慢初始化。

先执行下面命令确认当前安装和版本：

peekaboowin --version
uvx --upgrade --from git+https://github.com/wangneal/PeekabooWin peekaboowin --version

如果是 OCR 相关调用，再执行：

peekaboowin-setup

如果需要重新发布 OCR 模型到 GitHub Release，在仓库 Actions 中手动运行 Publish OCR Models workflow。它会下载 3 个模型 tar 并上传到 ocr-models Release。

把这个旧配置：

"args": ["--upgrade", "peekaboowin", "-y"]

改回：

"command": "peekaboowin"

如果是命令数组形式，把这个旧配置：

"command": ["uvx", "--upgrade", "peekaboowin", "-y"]

改回：

"command": ["peekaboowin"]

可手动验证 GitHub 最新版本：

uvx --upgrade --from git+https://github.com/wangneal/PeekabooWin peekaboowin --version

一键脚本版

新版本安装脚本支持重复运行即升级：

irm https://raw.githubusercontent.com/wangneal/PeekabooWin/main/install.ps1 | iex

如果客户机当前仍使用旧安装脚本，优先执行上面的 GitHub 安装命令，这是目前最稳的升级方式。

---

MCP 客户端配置

安装后，在不同客户端中添加以下配置。

OpenCode

配置文件: C:\Users\<用户名>\.config\opencode\opencode.json

推荐配置（使用已安装的 GitHub 最新版）：

{
  "mcp": {
    "peekaboowin": {
      "type": "local",
      "command": ["peekaboowin"],
      "enabled": true
    }
  }
}

不推荐：uvx 从 PyPI 启动

{
  "mcp": {
    "peekaboowin": {
      "type": "local",
      "command": ["uvx", "peekaboowin", "-y"],
      "enabled": true
    }
  }
}

当前建议优先使用 peekaboowin 本地命令；裸 uvx peekaboowin 会从 PyPI 下载，PyPI 未同步时可能仍是旧版。

Claude Desktop

配置文件: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "peekaboowin": {
      "command": "peekaboowin"
    }
  }
}

Cursor

设置路径: Settings → Features → MCP Servers → Add custom MCP

{
  "mcpServers": {
    "peekaboowin": {
      "command": "peekaboowin"
    }
  }
}

Windsurf

配置文件: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "peekaboowin": {
      "command": "peekaboowin"
    }
  }
}

GitHub Copilot (VS Code)

配置文件: .vscode/mcp.json

{
  "servers": {
    "peekaboowin": {
      "command": "peekaboowin"
    }
  }
}

所有客户端建议统一为 peekaboowin 本地命令。升级请单独运行 GitHub 安装命令，不要把 --upgrade 放在日常 MCP 启动配置里。

---

工具参考

共 32 个工具，按功能分类：

截图与屏幕

工具	参数	说明
screenshot	monitor?, region?, image_format?, quality?	捕获屏幕或区域截图
capture_window	hwnd, image_format?, quality?, max_width?	捕获指定窗口截图
list_monitors	—	列出所有显示器
health_check	—	系统诊断：DPI、权限、OCR 状态

UI 元素发现

工具	参数	说明
find_element	name?, class_name?, automation_id?, scope?	按名称/类名/ID 查找元素；UIA 无结果时自动 OCR 降级
get_element_info	element_ref	获取元素详细属性
get_children	element_ref, depth?	获取子元素树
get_desktop	depth?	获取桌面元素树
harvest_ui	target?, depth?	一站式 UI 发现，UIA 稀疏时自动 OCR 补充

元素引用格式: hwnd:12345 / point:100,200 / desktop

harvest_ui target: desktop（所有窗口）/ foreground（前台窗口）/ 12345（指定 HWND）

输入模拟

工具	参数	说明
click	x, y, button?, double?	鼠标点击（自动聚焦目标窗口）
move_mouse	x, y	移动鼠标（自动聚焦目标窗口）
drag	x1, y1, x2, y2, duration?	拖拽（自动聚焦起始窗口）
scroll	x, y, delta?	滚动（自动聚焦目标窗口）
type_text	text	输入 Unicode 文本（盲发，需先激活窗口）
press_keys	keys	按键组合：ctrl+s, alt+tab, win+r 等
click_element	element_ref	语义点击（自动聚焦目标窗口）
type_into_element	element_ref, text	语义输入（自动聚焦目标窗口）

press_keys 支持的键名（128+ 个）:

格式: press_keys("组合")，多个键用 + 连接，如 ctrl+s、alt+tab、win+r、ctrl+shift+escape。不区分大小写。

类别	键名	别名
修饰键	ctrl, alt, shift, win	control, lctrl/rctrl, lalt/ralt, lshift/rshift, lwin/rwin
导航	enter, tab, escape, space, backspace, delete	return, esc, back, del, forward_delete
方向	up, down, left, right	—
功能键	f1 ~ f24	—
编辑	home, end, pageup, pagedown, insert	pgup, pgdn, ins
锁定	capslock, numlock, scrolllock	—
小键盘	num0 ~ num9, numpad0 ~ numpad9	numseparator
小键盘运算	numpad_add, numpad_subtract, numpad_multiply, numpad_divide, numpad_decimal	num+, num-, num*, num/, num.
多媒体	volumeup, volumedown, volumemute, nexttrack, prevtrack, playpause, stop	—
浏览器	browserback, browserforward, browserrefresh, browserstop, browsersearch, browserfavorites, browserhome	—
启动	launchmail, launchcalculator, launchmedia, launchapp1, launchapp2	—
其他	printscreen, pause, break, apps, sleep, clear, help, select, execute, print	prtsc
符号单字符	= + - [ ] \ ; ' , . / ``	自动通过 VkKeyScanW 解析，+ 会自动按下 Shift

示例:

• press_keys("win") — 打开开始菜单
• press_keys("win+r") — 打开运行对话框
• press_keys("ctrl+shift+escape") — 打开任务管理器
• press_keys("alt+f4") — 关闭当前窗口
• press_keys("win+d") — 显示桌面

窗口管理

工具	说明
list_windows	列出所有可见窗口
get_foreground_window	获取前台窗口信息
activate_window hwnd	激活窗口到前台
move_window / resize_window	移动/调整窗口
minimize_window / maximize_window / restore_window	最小化/最大化/还原
close_window	发送 WM_CLOSE 关闭窗口

等待/轮询

工具	参数	说明
wait_for_element	name?, automation_id?, class_name?, control_type?, timeout?, interval?, visible?	等待元素出现/消失
wait_for_window	title?, class_name?, timeout?, interval?, appear?	等待窗口出现/消失

剪贴板

工具	参数	说明
read_clipboard	—	读取剪贴板文本
write_clipboard	text	写入剪贴板
paste_text	text	写入剪贴板 + Ctrl+V

OCR

工具	参数	说明
ocr_read	source?, hwnd?, region?, lang?	OCR 文本识别。source 自动推断：传 hwnd → window，传 region → region。region 格式: {"left":N,"top":N,"width":N,"height":N}

---

配置

通过环境变量配置，前缀 PEEKABOOWIN_：

变量	默认值	说明
PEEKABOOWIN_LOG_LEVEL	info	日志级别
PEEKABOOWIN_LOG_FORMAT	json	日志格式
PEEKABOOWIN_SCREENSHOT_FORMAT	png	截图格式
PEEKABOOWIN_SCREENSHOT_QUALITY	85	JPEG 质量
PEEKABOOWIN_SCREENSHOT_MAX_WIDTH	1920	截图最大宽度
PEEKABOOWIN_OCR_ENABLED	false	OCR 开关（有 paddleocr 时自动开启）
PEEKABOOWIN_OCR_LANGUAGE	ch	OCR 语言
PEEKABOOWIN_UIA_TIMEOUT	2.0	UIA 操作超时（秒）
PEEKABOOWIN_UIA_MAX_DEPTH	10	UIA 树遍历最大深度
PEEKABOOWIN_INPUT_CLICK_DELAY	0.05	点击后延迟（秒）
PEEKABOOWIN_INPUT_TYPE_DELAY	0.02	按键间延迟（秒）

示例:

{
  "mcpServers": {
    "peekaboowin": {
      "command": "peekaboowin",
      "env": {
        "PEEKABOOWIN_LOG_LEVEL": "debug",
        "PEEKABOOWIN_SCREENSHOT_MAX_WIDTH": "3840"
      }
    }
  }
}

---

AI Agent 提示词指南

核心规则

1. 每步操作后必须等待确认 — press_keys("win+r") 后必须 wait_for_window(title="运行")，不能连续发操作
2. 先观察后操作 — 用 screenshot / harvest_ui 了解界面状态再执行
3. 语义操作优先 — click_element / type_into_element 优于坐标操作
4. UWP 应用特殊处理 — UIA 树稀疏时 find_element 自动降级到 OCR，结果带 "source": "ocr_fallback" 标记

示例：打开记事本

press_keys("win+r")
wait_for_window(title="运行", timeout=3)
type_text("notepad")
press_keys("enter")
wait_for_window(title="记事本", timeout=5)
type_text("Hello from AI!")
screenshot()

自动聚焦说明

• click / click_element / type_into_element / drag / scroll / move_mouse 会自动 AttachThreadInput + SetForegroundWindow 激活目标窗口
• type_text / press_keys 是盲发操作，不会自动聚焦，使用前需 activate_window

---

架构

Tool Layer      — 32 个 @mcp.tool()，统一 @tool_error_handler 装饰器
Service Layer   — 单例服务，业务逻辑编排
Platform Layer  — comtypes (UIA) / ctypes (SendInput) / mss (截图) / PaddleOCR

三层职责清晰：Tool 层做参数校验，Service 层编排逻辑，Platform 层封装 Win32 API。

---

限制

• 仅 Windows 10/11 — 依赖 Windows UI Automation API
• UWP 应用 UIA 稀疏 — 自动降级到 OCR，但 OCR 元素缺少 automation_id / hwnd，无法用于 click_element
• 窗口截图 — capture_window 使用 PrintWindow(PW_RENDERFULLCONTENT) 优先，回退到屏幕裁剪，支持部分 UWP/DirectComposition 窗口
• 后台点击有限 — UIA InvokePattern 可实现后台操作，当前尚未实现
• UAC 隔离 — 非管理员进程无法向提升权限窗口发送输入

---

License

MIT