# 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:

```toml
[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`:

```toml
[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.

```powershell
.\scripts\install-codex.ps1
```

Custom paths:

```powershell
.\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:

```powershell
node .\server.mjs --smoke
```

MCP protocol test:

```powershell
node .\test-mcp-client.mjs
```

Debug a single helper action:

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

## Repository Layout

```text
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 配置示例：

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

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

```toml
[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`，并创建带时间戳的备份。

```powershell
.\scripts\install-codex.ps1
```

也可以指定自定义路径：

```powershell
.\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：

```powershell
node .\server.mjs --smoke
```

MCP 协议测试：

```powershell
node .\test-mcp-client.mjs
```

单独调试某个 helper action：

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

## 仓库结构

```text
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