Manual setup required. The maintainer's config contains paths only you know - edit the placeholders below before adding it to Claude Code.
1
Prepare the server locally
Run this once before adding it to Claude Code.
git clone https://github.com/alexlock1/macos-mcp-server.git
cd macos-mcp-server
npm install
npm run build2
Register it in Claude Code
claude mcp add macos-mcp -- node /path/to/macos-mcp-server/dist/index.jsReplace any placeholder paths in the command with the real path on your machine.
3
Make your agent remember this setup
macos-mcp's config, env vars, and the gotchas you hit — recalled in every future Claude Code, Cursor, and Codex session.
npx conare@latestFree · one command · indexes the sessions already on disk. Set up in the browser instead →
What it does
- Native file dialogs for picking and saving files
- System clipboard read and write capabilities
- Finder integration for revealing and selecting files
- Image processing tools including resizing and format conversion
- Apple Notes management for creating and reading notes
Tools 25
macos_pick_fileOpen file picker, return selected pathmacos_pick_folderOpen folder picker, return selected pathmacos_pick_filesMultiple file selectionmacos_save_dialogSave file dialog with default namemacos_clipboard_readGet clipboard text contentmacos_clipboard_writeSet clipboard text contentmacos_notifyDisplay system notificationmacos_open_urlOpen URL in default browsermacos_system_infoGet macOS version, hostname, usernamemacos_screen_resolutionGet screen dimensions and scale factormacos_reveal_in_finderReveal path in Findermacos_open_with_defaultOpen file with default appmacos_get_finder_selectionGet currently selected files in Findermacos_quick_lookOpen file with Quick Look previewmacos_screenshotTake screenshot (full screen, region, or window)macos_screenshot_clipboardScreenshot to clipboardmacos_image_infoGet image metadata (dimensions, format, etc.)macos_image_resizeResize image (width, height, or max size)macos_image_convertConvert between formats (jpeg, png, gif, tiff, bmp, heic)macos_pdf_page_countGet number of pages in PDFmacos_pdf_mergeMerge multiple PDFs into onemacos_note_createCreate a new notemacos_note_foldersList all foldersmacos_note_listList notes in a foldermacos_note_readRead note content by IDTry it
→Open a file picker to select a PDF document and tell me how many pages it has.
→Copy the text 'Hello, World!' to my system clipboard.
→Create a new note in the 'Work' folder titled 'Meeting Notes' with the content 'Discussion points...'.
→Reveal the file at /Users/me/Documents/report.pdf in Finder.
→Take a full-screen screenshot and save it to /tmp/screenshot.png.
Original README from alexlock1/macos-mcp
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