# macOS MCP Automation Server (`macos-mcp-automation`)

A Model Context Protocol (MCP) server providing rich macOS system automation, window management, and productivity tools. 

Designed for AI agents, it allows tools like Claude Desktop to interact with your Mac, run AppleScripts, open applications, retrieve browser tabs, take silent screenshots, search files via Spotlight, adjust system settings, and more.

## Quick Start (npx)

You can run this server directly via `npx` without installing it permanently:

```json
{
  "mcpServers": {
    "macos-automation": {
      "command": "npx",
      "args": ["-y", "macos-mcp-automation"]
    }
  }
}
```

Add the configuration above to your client configuration file, for example:
- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Cursor**: Settings > Features > MCP

---

## CLI Usage (Direct Terminal Commands)

In addition to starting an MCP server, this package works as a direct macOS desktop automation CLI. Running any command other than `mcp` triggers the action directly in your shell.

### Examples:
- **Lock Screen**: `npx macos-mcp-automation lock`
- **Volume control**: `npx macos-mcp-automation volume 50` (or `npx macos-mcp-automation volume` to print current volume)
- **Notification**: `npx macos-mcp-automation notify "Job complete!" "Build Agent"`
- **Take Screenshot**: `npx macos-mcp-automation screenshot` (saves to your Desktop)
- **Open App**: `npx macos-mcp-automation open "Spotify"`
- **Fetch active window**: `npx macos-mcp-automation active-window`
- **Show help guide**: `npx macos-mcp-automation help`

---

## macOS Security & Permissions

Because this tool simulates keystrokes and controls applications:
1. When you run tools like `type_text`, `press_key_combination`, or `get_active_window` for the first time, macOS will show a permission popup asking to grant the terminal/client **Accessibility** or **Automation** permissions.
2. Grant these permissions in **System Settings > Privacy & Security > Accessibility** and **Automation** for your terminal or Claude Desktop.

---

## Available Tools

The server exposes 17 high-level tools:

### System & Window Automation
- **`run_applescript`**: Execute any raw AppleScript on your system.
- **`open_app`**: Launch or focus any macOS application by name (e.g., `"Safari"`, `"Spotify"`, `"Terminal"`).
- **`quit_app`**: Quits or force-quits an application by name (e.g., `"Safari"`).
- **`list_apps`**: Returns a list of all currently open running applications.
- **`get_active_window`**: Retrieves the name of the active frontmost application and its window title.
- **`type_text`**: Simulates typing text character-by-character at the current cursor position.
- **`press_key_combination`**: Synthesizes key strokes and shortcuts (e.g., `["command", "ctrl"]` + `"q"` to lock).

### System Controls
- **`take_screenshot`**: Captures a full screenshot silently (no sound) and returns it directly to the LLM agent as a base64-encoded PNG image content block.
- **`get_volume`**: Gets the current output volume percentage.
- **`set_volume`**: Sets the output volume percentage (0-100).
- **`adjust_brightness`**: Adjusts screen brightness up or down by a set number of steps.
- **`lock_screen`**: Instantly locks the macOS screen.
- **`sleep_mac`**: Puts the Mac to sleep.
- **`display_notification`**: Displays a native macOS banner notification with title, subtitle, and body text.

### Productivity & Clipboard
- **`clipboard_get`**: Reads the text content currently stored in the system clipboard.
- **`clipboard_set`**: Writes text content to the system clipboard.
- **`spotlight_search`**: Searches files instantly using native macOS Spotlight (`mdfind`) with optional directory restriction.

### Browser Control
- **`get_browser_tabs`**: Fetches titles and URLs of all open tabs from Google Chrome, Safari, or both.
- **`open_browser_url`**: Opens a URL in the system default browser or specifically Safari / Chrome.

---

## Development & Local Testing

If you want to build and run the project locally:

### 1. Clone & Install Dependencies
```bash
git clone <repository-url>
cd macos_mcp
npm install
```

### 2. Build the Project
We use `tsup` to bundle TypeScript into a single-file executable ESM bundle inside `dist/index.js`:
```bash
npm run build
```

### 3. Run Locally (via absolute path)
Configure your MCP client to point to the local built file:
```json
{
  "mcpServers": {
    "macos-automation-local": {
      "command": "node",
      "args": ["/Users/YOUR_USER/path/to/macos_mcp/dist/index.js"]
    }
  }
}
```

---

## License

This project is licensed under the [MIT License](LICENSE).