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:
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):
{
"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