Skip to main content

PeekabooWin MCP

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

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

演示


系统要求

  • 操作系统: Windows 10 或 Windows 11
  • 工具: 推荐 uv(Python 包管理)
  • 权限: 管理员身份运行可解锁所有功能(向提升权限窗口发送输入)
  • OCR: 可选,项目固定使用 paddleocr==2.10.0 和 paddlepaddle==2.6.2(约 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 --force

# 安装后验证
peekaboowin --version

如果需要 OCR,再执行:

uv tool install --python 3.12 git+https://github.com/wangneal/PeekabooWin --force --with "paddleocr==2.10.0" --with "paddlepaddle==2.6.2"
peekaboowin-setup

OCR 依赖固定为 paddleocr==2.10.0 和 paddlepaddle==2.6.2,不要自行替换版本或放宽版本约束。

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

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

方式三:uvx 临时运行(仅用于一次性验证,不建议作为日常 MCP 配置)

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

裸 uvx peekaboowin 会从 PyPI 拉取版本;如果 PyPI 还没同步仓库当前版本,客户机可能仍启动旧的 0.1.0。不要在 MCP 客户端启动配置里长期加 uvx,否则每次启动都可能因联网解析依赖而触发 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 --force

# 如果客户机需要 OCR 扩展(固定版本)
uv tool install --python 3.12 git+https://github.com/wangneal/PeekabooWin --force --with "paddleocr==2.10.0" --with "paddlepaddle==2.6.2"

# 安装后验证
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,建议改为本地安装版,并把 MCP 配置改成:

"command": "peekaboowin"

如需临时验证仓库代码,可在 PowerShell 单独执行:

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

如果已经把 MCP 配置改成了 uvx,建议改回本地启动,避免客户端等待 uv 联网解析时出现 32001 超时。

如果首次就超时

通常有两种原因:

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

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

peekaboowin --version
uvx --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。

如果你还在用旧配置,请直接改成本地命令:

"command": "peekaboowin"

数组形式则写成:

"command": ["peekaboowin"]

不要再把 uvx 放到日常 MCP 启动配置里;它只适合临时验证。

例如这个旧配置:

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

也要改成:

"command": ["peekaboowin"]

可手动验证仓库代码:

uvx --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

推荐配置(使用已安装的 peekaboowin 命令):

{
  "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 安装命令,不要把 uvx 放在日常 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 开关(安装固定 OCR 依赖后自动开启)
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

Metadata

Release files for peekaboowin 0.1.26

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for peekaboowin 0.1.26
File Size Uploaded Provenance Actions
peekaboowin-0.1.26.tar.gz 73.8 kB Without provenance Details for peekaboowin-0.1.26.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for peekaboowin 0.1.26
File Interpreter ABI Platform Actions
peekaboowin-0.1.26-py3-none-any.whl Python 3 none any Details for peekaboowin-0.1.26-py3-none-any.whl

Total release size: 139.5 kB

Release files / peekaboowin-0.1.26.tar.gz

Download URL peekaboowin-0.1.26.tar.gz
Size 73.8 kB
Tags Source
SHA-256 checksum
How to use checksums
1d90275853eddac0bc4bb527043ac935954927662f97fa104b72b45d044f1d6b
BLAKE2b-256 checksum
How to use checksums
dca0401ce192f56f2b87a8da326cadd13ef85fa8801a730d29562f46456e634b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.2 {"installer":{"name":"uv","version":"0.11.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / peekaboowin-0.1.26-py3-none-any.whl

Download URL peekaboowin-0.1.26-py3-none-any.whl
Size 65.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1b5e5e5495ce67cb3186bf293958e657418acb5799fca577ddd8d386ddcc2120
BLAKE2b-256 checksum
How to use checksums
194c808a38e2668c74cf17e771ed2870ae6028b85a07c801a7222547c5f9d485
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.2 {"installer":{"name":"uv","version":"0.11.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for peekaboowin 0.1.26

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page