# macgic-mcp

macOS Accessibility MCP Server — gives AI "hands and eyes" on macOS.

An [MCP](https://modelcontextprotocol.io) server that exposes macOS Accessibility and Core Graphics APIs as tools, allowing AI systems (Claude, etc.) to fully control a Mac: clicking, typing, drawing, reading UI elements, launching apps, and taking screenshots.

## Requirements

- macOS
- Python 3.13+
- **Accessibility** permission granted to your terminal/IDE
- **Screen Recording** permission (for screenshots)

## Usage

Add to your MCP client config (e.g. Claude Code `~/.claude/mcp_servers.json` or Claude Desktop):

```json
{
  "mcpServers": {
    "macgic": {
      "command": "uvx",
      "args": ["macgic-mcp"],
      "type": "stdio"
    }
  }
}
```

## Tools

### Vision / Context
| Tool | Description |
|------|-------------|
| `screenshot` | Capture full screen, specific display, or region as PNG |
| `list_displays` | List connected displays with IDs, resolutions, positions |
| `list_apps` | List running applications (name, bundle ID, PID) |
| `get_ui_elements` | Read accessibility tree for an app (role, title, value, position, size) |

### Mouse Control
| Tool | Description |
|------|-------------|
| `mouse_click` | Click at x,y (left/right, single/double) |
| `mouse_move` | Move cursor to x,y |
| `mouse_drag` | Drag between points with smooth interpolation (enables drawing!) |
| `scroll` | Scroll at position (horizontal + vertical) |

### Keyboard Control
| Tool | Description |
|------|-------------|
| `type_text` | Type a string of text character by character |
| `key_press` | Press key combinations (e.g. `cmd+c`, `cmd+shift+z`, `enter`) |

### App Management
| Tool | Description |
|------|-------------|
| `open_app` | Launch an app by name or bundle ID |
| `activate_app` | Bring an app to the foreground |

## Permissions

Grant these in **System Settings > Privacy & Security**:

1. **Accessibility** — required for mouse/keyboard control and reading UI elements
2. **Screen Recording** — required for screenshots

## License

MIT
