WinCtl

WinCtl

为 Claude 和其他 MCP 客户端提供完整的 Windows 桌面访问能力
查看屏幕、读取并操作真实应用的 UI、管理窗口和 进程、处理文件并运行 shell 命令——所有操作均由分级 权限模型和审计日志保护。

---

为什么选择这个连接器

大多数桌面自动化服务都会给模型一张屏幕截图和一个 click(x, y) 工具，窗口一移动就会失效。这个服务围绕真正能让 Windows 自动化可靠运行的 要素构建：

• 优先使用 UI Automation。 uia_snapshot 会读取应用的辅助功能 树，因此 Claude 可以操作*“保存按钮”*，而不是使用很快就会失效的坐标。 uia_invoke 和 uia_set_value 可直接操作控件。
• 坐标始终准确。 进程会在调用任何 UI API 之前声明逐显示器 DPI 感知能力，并报告 DWM 窗口框架边界，而不是原始窗口矩形（其中包含一个不可见的约 7px 调整大小边框）。 如果没有这些处理，缩放显示器上的所有坐标都会悄然出错——在 200% 显示器上， GetWindowRect 报告的边缘位置是 1351px，而真实位置是 2641px。
• 输入确实能够送达。 合成输入会按节奏发送，因为批量发送 Unicode 按键事件会导致应用丢失或重复字符。超过 200 个字符的文本会改为通过剪贴板粘贴，之后还会恢复你的剪贴板内容。
• 句柄绝不会误导你。 窗口 ID 不透明且带有指纹；Windows 会重复使用窗口句柄，而过期句柄悄然指向另一个应用，正是导致自动化关闭错误窗口的原因。
• 如实报告失败。 window_focus 会验证前台窗口是否确实发生变化，并在 Windows 拒绝操作时明确说明。错误信息会解释下一步该做什么，而不是只显示 HRESULT。

要求

• Windows 10（1809+）或 Windows 11
• Node.js 20 或更高版本
• 无需编译器或构建工具——所有原生依赖都提供预构建二进制文件

安装

Claude Desktop（推荐）

从 最新版本下载 winctl.mcpb， 然后双击。Claude Desktop 会安装它，并在其 UI 中提供权限配置、允许的文件夹和确认设置。

Claude Code

先进行全局安装，然后注册命令：

npm install -g @sitharaj88/winctl
claude mcp add winctl -- winctl

在第二条命令中添加 --scope user，即可在每个项目中使用，而不只是当前项目。

请勿在此处使用 npx -y @sitharaj88/winctl。 这种方式可以运行，但 WinCtl 依赖 预构建的原生二进制文件（sharp、koffi），而 npx 每次启动时都会重新解析它们——耗时约 18 秒，而全局安装只需 3 秒。MCP 客户端会在此之前放弃，并报告 Connection closed。

任何 MCP 客户端（手动配置）

{
  "mcpServers": {
    "winctl": {
      "command": "winctl",
      "env": {
        "WINCTL_PROFILE": "standard"
      }
    }
  }
}

如果 winctl 不在你的 PATH 中，请直接指定入口文件——在 Windows 上， 全局 npm 安装会放在 %APPDATA%\npm\node_modules：

{
  "mcpServers": {
    "winctl": {
      "command": "node",
      "args": ["C:\\Users\\<you>\\AppData\\Roaming\\npm\\node_modules\\@sitharaj88\\winctl\\dist\\index.js"]
    }
  }
}

Claude Desktop 的配置文件位于 %APPDATA%\Claude\claude_desktop_config.json。

权限层级

每个工具恰好属于一个层级。已禁用层级中的工具绝不会被注册，因此模型无法看到或尝试使用这些工具，也不会花费上下文来读取其说明。

层级	允许的操作
observe	截图、枚举窗口/显示器、UI 树、系统和进程信息、读取文件
interact	鼠标和键盘输入、调用 UI Automation、聚焦/移动/关闭窗口、写入剪贴板
filesystem	创建、修改、移动和删除文件
manage	启动和终止进程、控制服务
shell	执行任意 PowerShell 和 cmd 命令

配置档会组合这些层级：

配置档	层级
readonly	observe
standard（默认）	observe、interact、filesystem
full	全部五个层级

# Pick a profile
WINCTL_PROFILE=readonly

# …or choose tiers explicitly
WINCTL_TIERS=observe,interact

配置

变量	默认值	用途
WINCTL_PROFILE	standard	readonly、standard 或 full
WINCTL_TIERS	—	显式指定层级列表，优先于配置档
WINCTL_ALLOWED_PATHS	—	文件工具可操作的文件夹，以分号分隔
WINCTL_DENIED_PATHS	—	额外拒绝访问的文件夹
WINCTL_CONFIRM_DESTRUCTIVE	true	执行破坏性操作前询问
WINCTL_AUDIT_LOG	%LOCALAPPDATA%\winctl\audit.jsonl	审计日志路径
WINCTL_AUDIT_DISABLED	false	关闭审计
WINCTL_MAX_IMAGE_WIDTH	1600	截图缩小后的宽度
WINCTL_COMMAND_TIMEOUT_MS	60000	Shell/PowerShell 时间限制

无法识别的配置档名称会以安全关闭的方式回退到 readonly，并在 stderr 中发出警告，而不会擅自猜测你的意图，从而可能授予写入权限。

工具

屏幕（5）

工具	层级	描述
screen_list_monitors	observe	显示器的位置、分辨率和 DPI 缩放比例
screen_capture	observe	截取某个显示器或整个虚拟桌面的屏幕
screen_capture_region	observe	截取矩形区域
screen_capture_window	observe	截取某个窗口，即使该窗口被其他窗口遮挡
screen_list_capturable_windows	observe	可单独截取的窗口

窗口（7）

工具	层级	描述
window_list	observe	显示可见的顶层窗口及其稳定 ID 和边界
window_get_active	observe	获取当前拥有键盘焦点的窗口
window_get_desktop_info	observe	获取虚拟桌面边界和光标位置
window_focus	interact	提升窗口并使其获得焦点，同时进行验证
window_set_state	interact	最小化、最大化、还原、隐藏、显示
window_move	interact	移动和调整大小（先取消最大化）
window_close	interact	请求关闭窗口

输入（7）

工具	层级	描述
input_move_mouse	interact	移动光标
input_click	interact	单击、右键单击或双击
input_drag	interact	在两点之间拖动，并插入中间位置
input_scroll	interact	垂直或水平滚动
input_type	interact	输入 Unicode 文本，较长文本则粘贴
input_press_keys	interact	按下组合键，例如 ctrl+shift+escape
input_key_hold	interact	按住或释放按键

UI 自动化（4）

工具	层级	描述
uia_snapshot	observe	读取应用的无障碍树
uia_find	observe	按名称、ID 或类型查找控件
uia_invoke	interact	单击、切换、展开、选择或聚焦控件
uia_set_value	interact	直接设置可编辑控件的文本

系统与进程（8）

工具	层级	描述
system_info	observe	操作系统、CPU、内存、磁盘、网络、电池、GPU
system_list_services	observe	列出服务及其状态和启动类型
system_list_installed_apps	observe	已安装的应用
system_notify	interact	Windows Toast 通知
system_control_service	manage	启动、停止或重启服务
process_list	observe	列出 CPU 和内存使用情况
process_start	manage	启动应用或打开文档
process_kill	manage	终止进程

文件、剪贴板与 shell（9）

工具	层级	描述
file_known_folders	observe	标准 Windows 路径和当前访问限制
file_list	observe	列出目录及文件大小和时间戳
file_read	observe	读取文本或 base64 内容
file_search	observe	按名称模式和内容查找文件
file_write	filesystem	写入、追加或创建
file_manage	filesystem	复制、移动、删除、创建目录
clipboard_read	observe	读取剪贴板文本
clipboard_write	interact	设置剪贴板文本
shell_run	shell	运行 PowerShell 或 cmd 命令

共 40 个工具。 每个工具都带有 title、readOnlyHint 和 destructiveHint 注释。

示例

“打开记事本，将我的会议笔记写入其中并保存到文档。”

Claude 通常会：

1. process_start → 启动记事本
2. window_list → 查找窗口及其所属进程 ID
3. window_focus → 确保按键输入发送到该窗口
4. input_type → 通过剪贴板粘贴笔记
5. input_press_keys ctrl+s，然后对文件名字段调用 uia_set_value
6. screen_capture_window → 通过屏幕确认结果

安全

• 分级控制是主要边界——已禁用的工具绝不会暴露。
• 路径限制会在检查前解析符号链接，因此允许文件夹中的链接无法访问被拒绝的文件夹。System32、WinSxS、Boot 和 Startup 文件夹在所有配置文件中都会被拒绝，包括 full。
• 确认：在执行破坏性操作前通过 MCP elicitation 确认。
• 审计日志：以 JSONL 格式记录每次调用，并对看起来敏感的参数进行脱敏。参见 PRIVACY.md。
• 释放修饰键：关闭时释放修饰键，避免崩溃发生在组合键按下过程中时 Ctrl 一直处于按下状态。
• 拒绝终止自身进程或 PID 0–4。

屏幕截图会捕获屏幕上的所有内容，并将其发送给你的 AI 服务提供商。在处理机密材料的设备上启用屏幕捕获前，请阅读 PRIVACY.md。

提权

Windows 会阻止普通权限进程自动化、捕获或向由提升权限进程拥有的窗口发送输入（UIPI）。如需操作管理员应用，请以提升权限运行连接器——否则这些调用会明确说明失败原因，而不会默默地什么也不做。

隐私政策

WinCtl 完全在你的设备上运行。它没有后端、遥测或分析功能，也不会自行发起网络请求。作者不会收到任何关于你或你的计算机的信息。

• **访问内容：**屏幕内容、窗口和应用状态、系统和进程信息、你允许访问的文件夹中的文件，以及剪贴板——仅在调用工具时访问。它会生成模拟输入，但绝不会记录你真实的键盘或鼠标活动。
• **数据去向：**你连接的 AI 客户端，仅此而已。工具返回的任何内容都会成为对话的一部分，因此受该客户端隐私政策的约束。屏幕截图会将屏幕上的所有内容发送给你的 AI 服务提供商——在处理机密材料的设备上启用屏幕捕获前，请考虑这一点。
• **存储内容：**仅有本地审计日志，位于 %LOCALAPPDATA%\winctl\audit.jsonl——每次工具调用占一行，并对看起来敏感的参数进行脱敏。它绝不会被上传。设置 WINCTL_AUDIT_DISABLED=1 可禁用日志，也可随时删除该文件。
• **保留和共享：**不会在设备外保留任何数据，也不会与第三方共享任何数据。
• **联系方式：**Sitharaj Seenivasan — [email protected]

完整政策：PRIVACY.md

开发

git clone https://github.com/sitharaj88/winctl
cd winctl
npm install
npm run build

npm run smoke                 # self-test against the live desktop
node scripts/smoke.mjs --full # full MCP protocol suite, including UI Automation
npm run inspect               # MCP Inspector UI

scripts/verify-interactive.mjs 会端到端操作记事本——启动应用、输入文本、通过 UI Automation 验证文本并进行清理。它会使用真实的鼠标和键盘，因此请勿在使用计算机时运行。

架构

src/
  index.ts              stdio entry point (DPI awareness runs first)
  http.ts               streamable HTTP entry point, loopback-only by default
  config.ts             profiles, tiers, limits
  security/             tier definitions, path containment, audit log, errors
  native/
    ffi.ts              koffi bindings to user32/kernel32/dwmapi
    dpi.ts              per-monitor DPI awareness
    handles.ts          opaque, fingerprinted window ids
    windows.ts          enumeration, focus, move, state
    input.ts            SendInput mouse and keyboard
    screen.ts           capture and token-aware encoding
    powershell.ts       per-call PowerShell execution
    uia.ts              UI Automation bridge
  server/
    registry.ts         tier gate + confirmation + audit in one place
    createServer.ts     assembles tools, resources and prompts
  tools/                the 40 tool definitions

如果要扩展此项目，以下两点实现细节值得了解：

• **PowerShell 每次调用都会启动一个进程。**使用常驻主机听起来更好，但 -Command - 会缓冲所有标准输入，直到流关闭后才执行，而不是逐条执行语句，因此永远不会返回结果。每次调用都启动进程也意味着脚本挂起不会影响后续调用。命令通过 -EncodedCommand（base64 UTF-16LE）传递，从而避免将 shell 引号处理作为注入漏洞的来源。
• **启动时会断言 INPUT 结构体的大小。**布局不匹配不会引发异常——而是会将鼠标事件发送到错误的坐标。

发布

npm run build && npm publish --access public   # npm
npx @anthropic-ai/mcpb pack                    # build the .mcpb bundle
mcp-publisher login github && mcp-publisher publish   # MCP registry

对于 Claude Connectors Directory，请通过扩展程序提交表单提交桌面扩展。

作者

Sitharaj Seenivasan

• 网站 — sitharaj.in
• GitHub — @sitharaj88
• LinkedIn — in/sitharaj08
• 电子邮件 — [email protected]

欢迎在 github.com/sitharaj88/winctl/issues 提交问题和功能请求。

许可

MIT © Sitharaj Seenivasan