applescript-mcp MCP Server

How to use

You connect your MCP client to the applescript-mcp server and issue tool requests that map to AppleScript-based actions on macOS. Each tool is organized into functional categories such as Calendar, Clipboard, Finder, Notifications, System, iTerm, Shortcuts, Mail, Messages, Notes, and Pages. You can sequence multiple tool calls to automate workflows, combine results from different categories, and incorporate user input or programmatic data into your scripts.

When you send a request, the server identifies the appropriate category and script, generates the AppleScript content, executes it via macOS, and returns the results to your client. If a script produces structured output, you receive it in a consistent MCP response so you can continue processing in your application.

How to install

Prerequisites you need before running the server are macOS 10.15 or later and Node.js 18 or later.

Follow these concrete steps to set up and run the server locally.

1. Clone or download the project and navigate to the project directory.

2. Install dependencies.

npm install

3. Build the server.

npm run build

4. Start the server locally using the runtime command shown in the configuration example.

node dist/index.js

5. Optionally, launch the MCP Inspector for testing and debugging.

npx @modelcontextprotocol/inspector node path/to/server/index.js

Configuration and startup details

You can configure how the server is started by providing an MCP configuration that points to the local runtime. A typical stdio-based configuration runs the server via Node.js and references the built output.

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

Additional notes

Debugging and logging are available via standard tooling. You can enable debug logs with an environment flag and observe detailed execution traces to troubleshoot AppleScript execution and MCP interactions.

If you want to see runtime behavior in real time, you can run the MCP Inspector to interact with the server through a web interface.

Example usage snippets

// Create a Pages document with plain text
create_document: { content: "Project Proposal\n\nThis document outlines the scope and timeline for the upcoming project." }

Notes on environment and permissions

Some features may require macOS permissions, such as Automation access, Full Disk Access, or Notification permissions. Ensure you grant the necessary permissions in System Settings so scripts can interact with applications and files.

add_calendar

Create a calendar event with a title and start/end times; optional calendar name.

list_calendar_today

List today's calendar events.

set_clipboard

Copy content to the system clipboard.

get_clipboard

Retrieve the current clipboard contents.

clear_clipboard

Clear the clipboard contents.

get_selected_files

Return files currently selected in Finder.

search_files

Search for files by query and optional location.

quick_look

Preview a file at a given path.

send_notification

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

toggle_do_not_disturb

Toggle Do Not Disturb mode.

volume

Set the system volume to a percentage value.

get_frontmost_app

Return the currently active application.

launch_app

Open a named application.

quit_app

Close an application, optionally forcing it.

toggle_dark_mode

Toggle the macOS dark mode setting.

paste_clipboard

Paste clipboard contents into iTerm.

run

Execute a command in iTerm, with optional new window.

run_shortcut

Run a macOS Shortcut by name with optional input.

list_shortcuts

List available shortcuts, with optional limit.

create_email

Compose a new email in the Mail app with recipient, subject, and body.

list_emails

List emails from a mailbox with optional filters.

get_email

Retrieve a specific email by search criteria.

list_chats

List available iMessage/SMS chats with optional participant details.

get_messages

Get messages from Messages app with optional limit.

search_messages

Search messages by text, sender, chat, or timeframe.

compose_message

Open Messages with a pre-filled message or send it automatically.

create

Create a markdown-formatted note in Notes.

createRawHtml

Create a note with raw HTML content in Notes.

list

List notes or notes within a specified folder.

get

Retrieve a note by title, optionally from a folder.

search

Search notes by query within an optional folder and limit.

create_document

Create a new Pages document from plain text content.