# 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
