macOS

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.