home / mcp / macos mcp server

macOS MCP Server

Provides native macOS operations through an MCP server, enabling file dialogs, clipboard, notifications, Finder integration, and more.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

You set up a macOS MCP Server to perform native macOS operations through a centralized, scriptable interface. With this server, you can open file dialogs, read and write the system clipboard, post notifications, reveal and manage Finder actions, take screenshots, and interact with images and PDFs, all from an MCP client. This enables automation and integration of macOS features into your workflows.

How to use

To use this MCP server, you run it as a local process and connect an MCP client to it. The client can request file dialogs, clipboard access, notifications, Finder actions, image and PDF tools, and notes operations. You can chain tasks from the client to create end-to-end automation, such as prompting the user to pick a file, processing it, notifying you when complete, and saving results.

How to install

Prerequisites: Node.js 18+ and macOS.

Clone the project, install dependencies, and build the server.

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

Configuration and runtime

Configure your MCP client to point to the local server. The server runs as a stdio MCP server using Node to execute the built index.

The final runtime command shown in the setup is:

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

This config tells the MCP client to start the server by invoking Node with the bundled index. Use the exact path to where you built the server.

Notes on usage patterns

You can request a single file or folder, enable multiple selections, or prompt for saving a file. You can read or write text to the clipboard, show system notifications with optional sounds, and open URLs in the default browser. When working with Finder, you can reveal files, open with the default application, or retrieve the current Finder selection.

Available tools and capabilities

The server exposes a suite of tools organized by category. Each tool returns data that you can use in subsequent steps of your automation.

Security considerations

Only run the MCP server on trusted systems. Limit network exposure if you enable remote access, and validate all inputs from clients before invoking macOS operations.

Troubleshooting

If the server fails to start, verify that Node.js 18+ is installed and that the build output exists at the specified path. Check file permissions for the dist/index.js file and ensure macOS can run AppleScripts via osascript.

Available tools

macos_pick_file

Open a file picker dialog and return the selected file path.

macos_pick_folder

Open a folder picker dialog and return the selected directory path.

macos_pick_files

Open a dialog allowing multiple file selections and return the selected paths.

macos_save_dialog

Open a save file dialog and return the chosen path and filename.

macos_clipboard_read

Read text content from the system clipboard.

macos_clipboard_write

Write text content to the system clipboard.

macos_notify

Display a system notification with a title, message, and optional sound.

macos_open_url

Open a URL in the default web browser.

macos_system_info

Return macOS version, hostname, and current user information.

macos_screen_resolution

Return screen dimensions and the scale factor.

macos_reveal_in_finder

Reveal a given path in Finder.

macos_open_with_default

Open a file with its default application.

macos_get_finder_selection

Get the currently selected files in Finder.

macos_quick_look

Open a file with Quick Look preview.

macos_screenshot

Take a screenshot of the full screen, a region, or a window.

macos_screenshot_clipboard

Capture a screenshot and place it on the clipboard.

macos_image_info

Get image metadata such as dimensions and format.

macos_image_resize

Resize an image by width, height, or maximum size.

macos_image_convert

Convert images between formats (jpeg, png, gif, tiff, bmp, heic).

macos_pdf_page_count

Get the number of pages in a PDF document.

macos_pdf_merge

Merge multiple PDFs into a single document.

macos_note_create

Create a new note in the Notes app.

macos_note_folders

List all note folders.

macos_note_list

List notes within a folder.

macos_note_read

Read note content by its ID.