Windows Universal MCP

English | 中文

Windows Universal MCP is a local Model Context Protocol server for controlling Windows desktop applications through generic Win32 automation.

It provides a small, dependency-free Windows bridge for common desktop actions: listing windows, launching apps, focusing windows, clicking, pasting Unicode text, sending keyboard shortcuts, taking screenshots, and monitoring output folders.

E-mail:heiak@foxmail.com

Features

• List visible top-level Windows application windows.

• Launch local executable files.

• Activate a window by hwnd.

• Click by client or screen coordinates.

• Paste Unicode text from an argument or UTF-8 text file.

• Send System.Windows.Forms.SendKeys keyboard sequences.

• Capture PNG screenshots of visible windows.

• Monitor a folder for newly created image files.

• Run as a stdio MCP server.

Related MCP server: Computer Use MCP

Requirements

• Windows

• Node.js 18+

• Windows PowerShell 5+

• An MCP client that supports stdio servers

No npm dependencies are required.

Installation

Clone or copy this repository, then configure your MCP client to launch server.mjs.

Codex example:

[mcp_servers.windows_universal]
command = "node"
args = ["D:\\path\\to\\windows-universal-mcp\\server.mjs"]
startup_timeout_sec = 30

If node is not in PATH, use an absolute path to node.exe:

[mcp_servers.windows_universal]
command = "C:\\Path\\To\\node.exe"
args = ["D:\\path\\to\\windows-universal-mcp\\server.mjs"]
startup_timeout_sec = 30

Restart the MCP client or open a fresh task after changing MCP config.

Optional Codex Installer

The install helper appends the MCP block to ~\.codex\config.toml and creates a timestamped backup.

.\scripts\install-codex.ps1

Custom paths:

.\scripts\install-codex.ps1 `
  -NodePath "C:\Path\To\node.exe" `
  -ServerPath "D:\path\to\windows-universal-mcp\server.mjs"

Tools

windows_list_windows

List visible top-level windows with handle, title, class name, process id, process name, process path, and bounds.

Arguments:

• titleContains: optional title substring filter.

• processContains: optional process name/path substring filter.

• includeEmptyTitles: include visible windows with empty titles.

windows_launch

Launch a local executable.

Arguments:

• path: absolute executable path.

• args: optional argument array.

• cwd: optional working directory.

• waitMs: optional delay after launch.

windows_activate

Bring a window to the foreground.

Arguments:

• hwnd: window handle from windows_list_windows.

windows_click

Click a window by coordinates.

Arguments:

• hwnd: target window handle.

• x: x coordinate.

• y: y coordinate.

• coordinateMode: client or screen.

• button: left, right, or middle.

• clicks: number of clicks.

windows_type_text

Paste Unicode text into the currently focused field of a window.

Arguments:

• hwnd: target window handle.

• text: text to paste.

• textPath: optional UTF-8 file to read text from.

• restoreClipboard: restore previous clipboard text after paste.

• submitWithEnter: press Enter after paste.

Use textPath for long text to avoid shell quoting and encoding issues.

windows_send_keys

Send a System.Windows.Forms.SendKeys sequence.

Arguments:

• hwnd: target window handle.

• keys: SendKeys syntax, such as ^v, {ENTER}, {TAB}, or %{F4}.

windows_screenshot

Capture a PNG screenshot of a visible window or a rectangle inside it.

Arguments:

• hwnd: target window handle.

• outputPath: output PNG path.

• rect: optional client-relative rectangle with x, y, width, height.

This uses screen capture, so the target window should be visible and unobscured.

windows_monitor_downloads

List newly created image files in a folder.

Arguments:

• folder: folder to inspect.

• sinceIso: optional ISO timestamp. Defaults to ten minutes ago.

• extensions: optional extension list.

Local Testing

Smoke test:

node .\server.mjs --smoke

MCP protocol test:

node .\test-mcp-client.mjs

Debug a single helper action:

$env:WIN_MCP_ARGS='{"includeEmptyTitles":false}'
node .\server.mjs --call-env windows_list_windows

Repository Layout

windows-universal-mcp/
  server.mjs
  windows-helper.ps1
  test-mcp-client.mjs
  package.json
  README.md
  LICENSE
  .gitignore
  scripts/
    install-codex.ps1

Safety Notes

• This tool controls local Windows UI. Review actions before using it with sensitive apps.

• Do not use it for passwords, payment forms, account creation, or sensitive data entry.

• Runtime screenshots and generated output folders are ignored by .gitignore.

License

MIT

中文

Windows Universal MCP 是一个本地 Model Context Protocol 服务器，用于通过通用 Win32 自动化能力控制 Windows 桌面应用。

它提供一个轻量、无 npm 依赖的 Windows 桌面桥接层，支持常见本地操作：列出窗口、启动程序、聚焦窗口、点击、粘贴 Unicode 文本、发送快捷键、窗口截图、监控输出目录。

功能

• 列出可见的 Windows 顶层应用窗口。

• 启动本地可执行文件。

• 通过 hwnd 激活窗口。

• 按客户端坐标或屏幕坐标点击。

• 从参数或 UTF-8 文本文件粘贴 Unicode 文本。

• 发送 System.Windows.Forms.SendKeys 快捷键序列。

• 截取可见窗口的 PNG 截图。

• 监控文件夹中新生成的图片文件。

• 作为 stdio MCP server 运行。

环境要求

• Windows

• Node.js 18+

• Windows PowerShell 5+

• 支持 stdio MCP server 的 MCP 客户端

不需要安装任何 npm 依赖。

安装

克隆或复制本仓库，然后在 MCP 客户端配置中启动 server.mjs。

Codex 配置示例：

[mcp_servers.windows_universal]
command = "node"
args = ["D:\\path\\to\\windows-universal-mcp\\server.mjs"]
startup_timeout_sec = 30

如果 node 不在 PATH 中，请使用 node.exe 的绝对路径：

[mcp_servers.windows_universal]
command = "C:\\Path\\To\\node.exe"
args = ["D:\\path\\to\\windows-universal-mcp\\server.mjs"]
startup_timeout_sec = 30

修改 MCP 配置后，需要重启 MCP 客户端，或打开一个新的任务/会话，让新 server 生效。

可选 Codex 安装脚本

安装脚本会把 MCP 配置追加到 ~\.codex\config.toml，并创建带时间戳的备份。

.\scripts\install-codex.ps1

也可以指定自定义路径：

.\scripts\install-codex.ps1 `
  -NodePath "C:\Path\To\node.exe" `
  -ServerPath "D:\path\to\windows-universal-mcp\server.mjs"

工具列表

windows_list_windows

列出可见顶层窗口，包含窗口句柄、标题、类名、进程 ID、进程名、进程路径和窗口边界。

参数：

• titleContains：可选，按窗口标题子串过滤。

• processContains：可选，按进程名或进程路径子串过滤。

• includeEmptyTitles：是否包含空标题窗口。

windows_launch

启动本地可执行文件。

参数：

• path：可执行文件绝对路径。

• args：可选，参数数组。

• cwd：可选，工作目录。

• waitMs：可选，启动后的等待毫秒数。

windows_activate

将窗口切到前台。

参数：

• hwnd：来自 windows_list_windows 的窗口句柄。

windows_click

按坐标点击窗口。

参数：

• hwnd：目标窗口句柄。

• x：x 坐标。

• y：y 坐标。

• coordinateMode：client 或 screen。

• button：left、right 或 middle。

• clicks：点击次数。

windows_type_text

向当前聚焦的输入区域粘贴 Unicode 文本。

参数：

• hwnd：目标窗口句柄。

• text：要粘贴的文本。

• textPath：可选，要读取的 UTF-8 文本文件路径。

• restoreClipboard：粘贴后是否恢复原剪贴板文本。

• submitWithEnter：粘贴后是否按 Enter。

长文本建议使用 textPath，避免命令行引号和编码问题。

windows_send_keys

发送 System.Windows.Forms.SendKeys 快捷键序列。

参数：

• hwnd：目标窗口句柄。

• keys：SendKeys 语法，例如 ^v、{ENTER}、{TAB} 或 %{F4}。

windows_screenshot

截取可见窗口或窗口内指定矩形区域，保存为 PNG。

参数：

• hwnd：目标窗口句柄。

• outputPath：输出 PNG 路径。

• rect：可选，客户端坐标矩形，包含 x、y、width、height。

该功能使用屏幕截图，所以目标窗口应保持可见且不被遮挡。

windows_monitor_downloads

列出某个文件夹中新生成的图片文件。

参数：

• folder：要检查的文件夹。

• sinceIso：可选，ISO 时间戳，默认检查最近十分钟。

• extensions：可选，扩展名列表。

本地测试

Smoke test：

node .\server.mjs --smoke

MCP 协议测试：

node .\test-mcp-client.mjs

单独调试某个 helper action：

$env:WIN_MCP_ARGS='{"includeEmptyTitles":false}'
node .\server.mjs --call-env windows_list_windows

仓库结构

windows-universal-mcp/
  server.mjs
  windows-helper.ps1
  test-mcp-client.mjs
  package.json
  README.md
  LICENSE
  .gitignore
  scripts/
    install-codex.ps1

安全说明

• 该工具会控制本地 Windows UI。对敏感应用执行操作前，请先确认操作内容。

• 不建议用于密码、支付表单、账号创建或敏感数据输入。

• 运行截图和生成输出目录已在 .gitignore 中忽略。

License / 许可证

MIT