Skip to content
Conduit

mcp server

wsl-computer-use-mcp

Computer-use MCP server: let AI agents control the Windows desktop from WSL — semantic (UI Automation) + coordinate modes, 20 tools

q18857450491-ux/wsl-computer-use-mcpcommunitylistedunreviewed
Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

  • Node.js 20 or newer
~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "wsl-computer-use-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "wsl-computer-use-mcp"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 22, 2026

Pi Computer-Use MCP

让 Pi 能直接操控 Windows 桌面（从 WSL 内发起）。

它做什么

本 MCP 服务器跑在 WSL（Node 进程），通过 /mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe 调用 Windows 侧的 .NET 与 user32.dll，从而对真实的 Windows 桌面截屏、移动鼠标、敲键盘、操作窗口。

Pi (WSL) ──stdio──> index.js (Node) ──powershell.exe──> Windows 桌面

安装

1. 前置条件

  • Windows 10/11 + WSL2（本服务器跑在 WSL 里，操控 Windows 桌面）
  • WSL interop 必须开启（默认开启）：/etc/wsl.conf 里不要有 interop.enabled = false
  • Node.js >= 20

2. 获取代码

git clone https://github.com/q18857450491-ux/wsl-computer-use-mcp.git
cd wsl-computer-use-mcp
npm install

3. 注册到 MCP 客户端

Pi（配合 pi-mcp-adapter） —— 把下面内容写进 ~/.pi/agent/mcp-adapter.json：

{
  "mcpServers": {
    "computer-use": {
      "command": "node",
      "args": ["/abs/path/to/wsl-computer-use-mcp/index.js"]
    }
  }
}

⚠️ 文件名必须是 mcp-adapter.json —— pi-mcp-adapter 不读 mcp.json（那个归 Pi 内置 MCP 用）。 仓库里的 mcp-adapter.example.json 可直接改路径使用。

其他 MCP 客户端（Claude Desktop、Cursor、Cline 等）：把同样的 mcpServers 段放进它们的配置文件即可。

4. 验证

node test.js        # 只读测试：截屏 / 列窗口 / 读剪贴板 —— 不会动鼠标键盘

看到 结果：5 通过 / 0 失败 即安装成功。

5. 试试看

在 AI 客户端里直接说：

  • 「截个屏，看看现在屏幕上是什么」
  • 「打开记事本，输入『你好』」
  • 「列出所有窗口」
  • 「点一下计算器的 7」

20 个工具（两种模式）

语义模式（UIA）—— 推荐先用

工具说明
list_elements列出窗口内控件：类型、文字、位置、可用模式（Invoke/Value…）。能直接读到按钮文字
click_element点击控件。优先 InvokePattern —— 不移动鼠标、不抢键盘焦点
set_text往输入框写值（ValuePattern.SetValue）—— 不敲键盘，中文/emoji 无忧
read_element读控件内容（输入框的值、文本块的文字）
focus_element把键盘焦点移到控件（只改焦点，不发按键）

坐标模式（user32.dll 输入模拟）

工具说明
screen_info屏幕尺寸、显示器列表、光标坐标、前台窗口句柄
screenshot截图。format=image 返回图片；format=file 存盘返回路径。scale 控制缩放（默认 0.75）
mouse_move移动鼠标到 (x, y)
mouse_click点击（左/右/中，单击/双击/三击），可带坐标
mouse_drag拖拽（选中文本、拖动窗口/文件）
scroll滚轮，正数向上
key_press组合键：ctrl+c、alt+tab、win+r、ctrl+shift+t、f5…
type_text输入文本。默认走「剪贴板 + Ctrl+V」，中文/emoji 都能可靠输入
list_windows列出所有窗口（句柄/PID/进程/标题/位置），标记前台窗口
focus_window激活窗口（用 handle / pid / title 指定）
window_actionrestore / minimize / maximize / close
launch_app启动程序、打开文件或 URL
get_clipboard读剪贴板
set_clipboard写剪贴板（支持中文）
run_powershell执行任意 PowerShell（万能后备）

该用哪种模式

语义模式（UIA）坐标模式
定位方式按控件文字/类型（"取消"、Button）屏幕像素坐标
侵入性非侵入 —— 不夺鼠标、不抢焦点，你可同时用电脑侵入 —— 操作期间鼠标会自己动
通用性依赖应用的 UIA 支持任何界面都能用（游戏、canvas、自绘 UI）
可靠性界面改版也不易失效界面一变坐标就废

推荐流程：list_elements 找出控件 → click_element / set_text 操作 → 若控件无 Invoke/Value 模式，再退回坐标模式（screenshot + mouse_click / type_text）。

UIA 覆盖率实测（2026-09-29）

应用类型支持度实测结果
UWP / 现代应用（计算器、Windows 设置）✅ 完整计算器 52 控件、设置 51 控件；Invoke、Value 模式齐全，点击/写入全通过
Chromium（Chrome / Edge）✅ 良好读到 2235 个控件，Button | 关闭 | Invoke,ScrollItem
Win11 记事本（XAML Islands 混合）⚠️ 差只暴露 2 个 Pane，编辑区无 UIA
老式 Win32 对话框（Win+R 运行框）⚠️ 差控件全退化为 Pane，无 Value/Invoke 模式

→ 这正是必须双轨的原因：语义模式精准但不通用，坐标模式通用但侵入。

list_elements 支持 filter（按文字搜）、interactiveOnly（只列可交互控件）、maxItems/maxDepth 控制输出量。默认最多 60 条，避免像 Chrome 那样一次吐出 2235 个。

坐标系统

坐标基于虚拟桌面（多显示器时是一整块画布）。 先用 screen_info 看 virtual.x / virtual.y / virtual.width / virtual.height， 再用 screenshot 观察实际布局。注意：截图若用了 scale < 1， 图片上的像素坐标要除以 scale 才是真实坐标。

关于中文输入

type_text 默认用剪贴板法：先把文本写入剪贴板 → 发 Ctrl+V → 恢复原剪贴板内容。 因此中文、emoji、任何特殊符号都不会出问题。

如果想逐键敲（保留剪贴板），传 method: "sendkeys"，但该方式对非 ASCII 支持很差。

环境变量

变量默认值说明
COMPUTER_USE_POWERSHELL/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exePowerShell 路径
COMPUTER_USE_SCALE0.75截图默认缩放
COMPUTER_USE_SHOT_DIR/tmp/computer-use-shotsformat=file 时的存盘目录

自测

cd ~/.pi/mcp-servers/computer-use
node test.js          # 只读测试，不会动鼠标键盘

已知限制

  • 需要 WSL interop：若 /etc/wsl.conf 里 interop.enabled=false，本服务器无法工作。
  • 每次调用约 0.2–1s：PowerShell 每次都要 Add-Type 编译 P/Invoke 声明（约 300ms 开销）。
  • Windows 前台锁定：focus_window 可能被 Windows 的 SetForegroundWindow 策略拒绝（返回 false）， 重试通常可成功，或改用点击任务栏。
  • 首次截图较慢：首次加载 System.Drawing 需 1–5 秒。
  • 安全软件：卡巴斯基等可能把「模拟鼠标键盘」判为可疑行为，建议把 powershell.exe 与本项目所在目录加入排除项（路径形如 \\wsl.localhost\<发行版名>\<你的家目录>\...）。

安全须知

这套工具等同于把 Windows 桌面的完全控制权交给 AI： 能点任何按钮、输任何内容、执行任意 PowerShell。 run_powershell 风险最高——它可以在 Windows 上做任何当前用户权限内的事。

卸载

# 1. 从 pi 的 MCP 配置中移除
rm ~/.pi/agent/mcp-adapter.json     # 或删掉其中 computer-use 这一项

# 2. 删除本目录
rm -rf ~/.pi/mcp-servers/computer-use

License

MIT

↑↓ navigate openesc close