# desktop-automation-mcp

Windows desktop automation MCP server — screenshot, mouse, keyboard, and image recognition. Built for Claude Code and other MCP clients.

**14 tools · Python 3.10+ · FastMCP · stdio transport**

## Features

- 🖱️ **Mouse** — click, double-click, right-click, move (smooth), drag
- ⌨️ **Keyboard** — type text, press single keys, key combinations (hotkeys)
- 📸 **Screenshot** — full screen or region capture
- 🔍 **Image recognition** — locate UI elements on screen by image template
- 🌐 **CJK text input** — Chinese/Japanese/Korean via clipboard paste
- 📏 **Screen info** — cursor position, screen resolution
- ⚠️ **Alert** — pop up desktop notification dialogs

## Why this one?

Most desktop automation MCP servers are built by English-speaking developers and struggle with CJK text input. This server:

- **Native CJK support** — non-ASCII text automatically routes through clipboard paste
- **Minimal & readable** — 172 lines of Python, no black magic
- **FastMCP stdio** — latest MCP protocol, clean and reliable

## Install

```bash
git clone https://github.com/Lianne0106/desktop-automation-mcp.git
cd desktop-automation-mcp
pip install -r requirements.txt
```

For `locate_on_screen` (image recognition), also install OpenCV:

```bash
pip install opencv-python
```

## Claude Code setup

Add to `~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "desktop-automation": {
      "command": "python",
      "args": ["PATH\\TO\\desktop-automation-mcp\\server.py"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}
```

Restart Claude Code, then try:

```
> 截个屏看看
> 鼠标移到屏幕中央
> 帮我输入这段中文
```

## Tools

| Tool | Description |
|------|-------------|
| `screenshot` | Capture full screen or region |
| `click` | Click at (x, y), any mouse button |
| `double_click` | Double-click at (x, y) |
| `right_click` | Right-click at (x, y) |
| `move` | Smoothly move cursor to (x, y) |
| `drag` | Click-drag from A to B |
| `type_text` | Type text (clipboard for CJK, keystrokes for ASCII) |
| `press_key` | Press a single key (enter, tab, escape, f1-f12, etc.) |
| `hotkey` | Key combination (ctrl+c, alt+tab, win+r, etc.) |
| `scroll` | Scroll wheel up/down, optionally at a position |
| `get_position` | Get current cursor position |
| `get_screen_size` | Get screen dimensions |
| `locate_on_screen` | Find an image template on screen |
| `alert` | Show a popup alert dialog |

## Failsafe

Move mouse to the top-left corner to abort any running action (PyAutoGUI FAILSAFE).

## Similar projects

- [windows-computer-use-mcp](https://github.com/sandraschi/windows-computer-use-mcp) — 22 tools, UI Automation, OCR, autonomous agent
- [WindowsOSMCP](https://github.com/felenko/WindowsOSMCP) — DPI-aware, multi-monitor, UIA element targeting
- [pc-control-mcp](https://github.com/Nanonite-crypto/pc-control-mcp) — 30+ tools, Playwright browser, notes, clipboard

## License

MIT