npm package: @pilotgentic/mcp-server
Description: Physical macOS desktop control for Claude — click, type, screenshot, read UI structure, control browsers, run agentic action loops via PilotGentic daemon
Author: PilotGentic
Latest version: 1.0.0

# MacPilot MCP Server

Gives Claude CLI (Claude Code) physical Mac control + vision via the MacPilot daemon. Claude can see your screen, click anywhere, type text, press keyboard shortcuts, scroll, and launch apps — across every native Mac application.

## Install (one command)

```bash
cd ~/Projects/automation-hub/MacPilot/components/mcp-server
./install.sh
```

That's it. The installer handles everything:

1. Installs Node.js dependencies
2. Registers the MCP server via `claude mcp add` (user scope → `~/.claude.json`) so tools work from any directory
3. Creates `.mcp.json` in the project root as a project-scope backup
4. Installs the MacPilot skill so Claude knows *when and how* to use the tools (`~/.claude/skills/macpilot/`)
5. The daemon auto-starts when Claude connects — no manual launch needed

After install, just run `claude` from any directory. The tools are always available.

```bash
claude
> "Open System Settings and enable Dark Mode"
# Claude auto-uses: screenshot → launch → click → verify
```

---

## Available Tools

| Tool | Description |
|------|-------------|
| `pilotgentic_screenshot` | Capture screen — gives Claude vision of the Mac desktop |
| `pilotgentic_click` | Click at (x,y) coordinates in any app |
| `pilotgentic_type` | Type text into the focused field |
| `pilotgentic_key` | Press keyboard shortcuts (Cmd+C, Cmd+V, etc.) |
| `pilotgentic_scroll` | Scroll at a specific position |
| `pilotgentic_move` | Move Doppler cursor overlay (aim without clicking) |
| `pilotgentic_launch` | Open or activate a Mac application |
| `pilotgentic_status` | Get daemon status, cursor position, running apps |

## Architecture

```
Claude Code <-> MCP (stdio) <-> This Server <-> File IPC <-> Daemon <-> Mac
```

The MCP server communicates with the MacPilot daemon via file-based IPC (`/tmp/pilotgentic_cmd.txt` and `/tmp/pilotgentic_result.txt`). The daemon uses macOS CGEvents for physical input simulation in any app.

---

## How It Works Under the Hood

The installer sets up 3 layers that work together:

| Layer | What it does | File |
|-------|-------------|------|
| **MCP Server (user)** | Registers 8 tools in every Claude CLI session | `~/.claude.json` (via `claude mcp add`) |
| **MCP Server (project)** | Backup: tools available when inside MacPilot dir | `.mcp.json` in project root |
| **Skill** | Teaches Claude the screenshot->click->verify workflow | `~/.claude/skills/macpilot/SKILL.md` |
| **Daemon auto-start** | Spawns MacPilot daemon if not running | Built into MCP server startup |

The MCP server layer makes the tools *available*. The skill layer makes Claude *prefer* them for GUI tasks and know the correct workflow. The auto-start layer means users never need to manually launch the daemon.

### Manual Setup (if you prefer)

If you don't want to use the installer, you can set up each layer manually:

**1. MCP Server (user scope)** — Register via Claude CLI so tools are available everywhere:

```bash
claude mcp add macpilot --scope user -- node /path/to/MacPilot/components/mcp-server/src/index.js
```

This writes to `~/.claude.json`. Verify with `claude mcp list`.

**2. MCP Server (project scope)** — Create `.mcp.json` in the MacPilot project root:

```json
{
  "mcpServers": {
    "macpilot": {
      "command": "node",
      "args": ["/path/to/MacPilot/components/mcp-server/src/index.js"]
    }
  }
}
```

**3. Skill** — Create `~/.claude/skills/macpilot/SKILL.md` with YAML frontmatter containing `name`, `description`, `allowed-tools`, and the MacPilot workflow instructions. See `install.sh` for the full content.

**Important:** Claude Code does NOT use `~/.claude/settings.json` for MCP servers. That file is for permissions and general settings. MCP servers go in `~/.claude.json` (user scope) or `.mcp.json` (project scope). Use `claude mcp add` to register them correctly.

---

## File Structure

```
mcp-server/
├── package.json
├── install.sh                  # One-command installer
├── mcp.json                    # MCP config for --mcp-config flag
├── README.md
└── src/
    ├── index.js                # Server entry point
    ├── config/
    │   └── constants.js        # Paths, timeouts, key codes
    ├── tools/
    │   ├── index.js            # Tool registry
    │   ├── click.js            # pilotgentic_click
    │   ├── type.js             # pilotgentic_type
    │   ├── key.js              # pilotgentic_key
    │   ├── scroll.js           # pilotgentic_scroll
    │   ├── screenshot.js       # pilotgentic_screenshot
    │   ├── status.js           # pilotgentic_status
    │   ├── move.js             # pilotgentic_move
    │   └── launch.js           # pilotgentic_launch
    └── utils/
        ├── daemon-bridge.js    # File-based IPC with daemon
        ├── daemon-lifecycle.js # Daemon auto-start/health check
        ├── screenshot.js       # Screen capture utilities
        └── applescript.js      # AppleScript system queries
```

## Prerequisites

- **Node.js** (v18+) — the installer checks for this
- **macOS** — the daemon uses CGEvents (macOS-only)
- **Claude CLI** (Claude Code) — install from [claude.ai](https://claude.ai)
- **Accessibility permissions** — macOS will prompt you to grant accessibility access on first use (System Settings > Privacy & Security > Accessibility)