# mcp-control

MCP server that gives Claude Code full mouse, keyboard, and app control on macOS. Tell Claude what to do and watch it operate your computer.

Pair with [mcp-screen](https://github.com/andrefigueira/mcp-screen) for vision + control.

## Setup

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

```json
{
  "mcpServers": {
    "control": {
      "command": "npx",
      "args": ["mcp-control"]
    }
  }
}
```

Restart Claude Code. Done.

## Usage

Just tell Claude what to do:

- "Open Safari and go to github.com"
- "Click the search box and type my query"
- "Fill in this form - name is Andre, email is..."
- "Switch to Slack and send a message"
- "Scroll down on this page"

## Tools

### Mouse
| Tool | Description |
|------|-------------|
| `mouse_move` | Move cursor to (x, y) |
| `mouse_click` | Click at (x, y) with left/right, single/double/triple |
| `mouse_drag` | Drag from one point to another |
| `mouse_scroll` | Scroll up/down/left/right |
| `get_cursor_position` | Get current cursor coordinates |

### Keyboard
| Tool | Description |
|------|-------------|
| `type_text` | Type a string into the focused field |
| `press_key` | Press a key combo (e.g. cmd+c, tab, enter) |

### App Control
| Tool | Description |
|------|-------------|
| `get_frontmost_app` | Get focused app name and bundle ID |
| `focus_app` | Bring an app to the front |
| `list_windows` | List all visible windows with positions and sizes |

### Batch
| Tool | Description |
|------|-------------|
| `run_actions` | Execute a sequence of actions in one call - click, type, press keys, switch apps |

The `run_actions` tool is the key for speed. Instead of one tool call per action (each with Claude think time), it batches everything into a single round-trip.

## How It Works

Uses macOS Core Graphics events via JXA (JavaScript for Automation) and AppleScript. Zero external dependencies - just built-in macOS tools.

- Mouse control: CGEvent API (sub-millisecond)
- Keyboard: AppleScript keystroke (handles Unicode)
- Key combos: CGEvent with modifier flags
- App control: AppleScript

## Permissions

Your terminal needs **Accessibility** permission:

**System Settings > Privacy & Security > Accessibility** - enable your terminal app.

## Requirements

- macOS
- Node.js >= 18

## Author

[@voidmode](https://x.com/voidmode)

## License

MIT