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)

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.

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:

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:

{
  "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
• Accessibility permissions — macOS will prompt you to grant accessibility access on first use (System Settings > Privacy & Security > Accessibility)