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