# macOS MCP Server

An MCP (Model Context Protocol) server for macOS system operations: file dialogs, clipboard, notifications, and Finder integration.

## Features

- **File Dialogs**: Open file/folder pickers, save dialogs, multiple selection
- **Clipboard**: Read and write text to system clipboard
- **System**: Notifications, open URLs, get system info
- **Finder**: Reveal files, open with default app, get current selection

## Tools

### File Dialogs
| Tool | Description |
|------|-------------|
| `macos_pick_file` | Open file picker, return selected path |
| `macos_pick_folder` | Open folder picker, return selected path |
| `macos_pick_files` | Multiple file selection |
| `macos_save_dialog` | Save file dialog with default name |

### Clipboard
| Tool | Description |
|------|-------------|
| `macos_clipboard_read` | Get clipboard text content |
| `macos_clipboard_write` | Set clipboard text content |

### System
| Tool | Description |
|------|-------------|
| `macos_notify` | Display system notification |
| `macos_open_url` | Open URL in default browser |
| `macos_system_info` | Get macOS version, hostname, username |
| `macos_screen_resolution` | Get screen dimensions and scale factor |

### Finder
| Tool | Description |
|------|-------------|
| `macos_reveal_in_finder` | Reveal path in Finder |
| `macos_open_with_default` | Open file with default app |
| `macos_get_finder_selection` | Get currently selected files in Finder |
| `macos_quick_look` | Open file with Quick Look preview |

### Screenshot
| Tool | Description |
|------|-------------|
| `macos_screenshot` | Take screenshot (full screen, region, or window) |
| `macos_screenshot_clipboard` | Screenshot to clipboard |

### Image Tools (sips)
| Tool | Description |
|------|-------------|
| `macos_image_info` | Get image metadata (dimensions, format, etc.) |
| `macos_image_resize` | Resize image (width, height, or max size) |
| `macos_image_convert` | Convert between formats (jpeg, png, gif, tiff, bmp, heic) |

### PDF Tools
| Tool | Description |
|------|-------------|
| `macos_pdf_page_count` | Get number of pages in PDF |
| `macos_pdf_merge` | Merge multiple PDFs into one |

### Notes App
| Tool | Description |
|------|-------------|
| `macos_note_create` | Create a new note |
| `macos_note_folders` | List all folders |
| `macos_note_list` | List notes in a folder |
| `macos_note_read` | Read note content by ID |

## Installation

Clone and build:

```bash
git clone https://github.com/alexlock1/macos-mcp-server.git
cd macos-mcp-server
npm install
npm run build
```

## Configuration

Add to your MCP settings (e.g., `.mcp.json` or Claude Desktop config):

```json
{
  "mcpServers": {
    "macos": {
      "command": "node",
      "args": ["/path/to/macos-mcp-server/dist/index.js"]
    }
  }
}
```

## Usage Examples

### Pick a file

```
macos_pick_file({
  prompt: "Select a document",
  fileTypes: ["pdf", "doc", "docx"]
})
```

### Copy to clipboard

```
macos_clipboard_write({ text: "Hello, World!" })
```

### Show notification

```
macos_notify({
  title: "Task Complete",
  message: "Your file has been processed",
  sound: "Glass"
})
```

### Get system info

```
macos_system_info({})
// Returns: { computerName, userName, homeDirectory, osVersion }
```

### Reveal in Finder

```
macos_reveal_in_finder({ path: "/Users/me/Documents/report.pdf" })
```

### Take a screenshot

```
macos_screenshot({
  path: "/tmp/screenshot.png",
  fullScreen: true
})
```

### Resize an image

```
macos_image_resize({
  inputPath: "/path/to/image.png",
  outputPath: "/path/to/resized.png",
  maxSize: 800
})
```

### Get PDF page count

```
macos_pdf_page_count({ path: "/path/to/document.pdf" })
```

### Create a note

```
macos_note_create({
  name: "Meeting Notes",
  body: "Discussion points...",
  folder: "Work"
})
```

## Requirements

- Node.js 18+
- macOS (uses AppleScript for all operations)

## How It Works

All operations use AppleScript via `osascript` to interact with macOS system features. This provides native dialog appearances and full system integration.

## License

MIT