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.

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