AppleScript MCP server

The AppleScript MCP server provides a standardized interface for AI applications to interact with macOS through AppleScript. It enables control of system functions, file management, notifications, and various macOS applications like Calendar, Notes, Mail, and Messages.

Prerequisites

• macOS 10.15 or later
• Node.js 18 or later

Installation

To get started with the AppleScript MCP server:

# Install dependencies
npm install

# Build the server
npm run build

After building the server, add the following to your mcp.json file:

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

Permissions Setup

Some features require specific macOS permissions:

• For notifications: Enable in System Settings > Notifications > Script Editor
• For Messages, Mail, and other app access: Check System Preferences > Security & Privacy > Privacy > Automation
• For Messages database access: Grant Full Disk Access permission

Available Features

Calendar Management

Available Commands

Examples

# Create a new calendar event
Create a calendar event titled "Team Meeting" starting tomorrow at 2pm for 1 hour

# List today's events
What events do I have scheduled for today?

Clipboard Operations

Available Commands

Examples

# Copy text to clipboard
Copy "Remember to buy groceries" to my clipboard

# Get clipboard contents
What's currently in my clipboard?

# Clear clipboard
Clear my clipboard

Finder Integration

Available Commands

Examples

# Get selected files in Finder
What files do I currently have selected in Finder?

# Search for files
Find all PDF files in my Documents folder

# Preview a file
Show me a preview of ~/Documents/report.pdf

System Notifications

Available Commands

Examples

# Send a notification
Send me a notification with the title "Reminder" and message "Time to take a break"

# Toggle Do Not Disturb
Turn on Do Not Disturb mode

System Controls

Available Commands

Examples

# Set system volume
Set my Mac's volume to 50%

# Get active application
What app am I currently using?

# Launch an application
Open Safari

# Quit an application
Close Spotify

# Toggle dark mode
Switch to dark mode

iTerm Terminal Integration

Available Commands

Examples

# Paste clipboard to iTerm
Paste my clipboard contents into iTerm

# Run a command in iTerm
Run "ls -la" in iTerm

# Run a command in a new iTerm window
Run "top" in a new iTerm window

Shortcuts Automation

Available Commands

Examples

# List available shortcuts
List all my available shortcuts

# List with limit
Show me my top 5 shortcuts

# Run a shortcut
Run my "Daily Note in Bear" shortcut

# Run a shortcut with input
Run my "Add to-do" shortcut with input "Buy groceries"

Mail Integration

Available Commands

Examples

# Create a new email
Compose an email to [email protected] with subject "Meeting Tomorrow" and body "Hi John, Can we meet tomorrow at 2pm?"

# List emails
Show me my 10 most recent unread emails

# Get a specific email
Find the email from [email protected] about "Project Update"

Messages Integration

Available Commands

Examples

# List available chats
Show me my recent message conversations

# Get recent messages
Show me my last 20 messages

# Search messages
Find messages containing "dinner plans" from John in the last week

# Compose a message
Send a message to 555-123-4567 saying "I'll be there in 10 minutes"

Notes Management

Available Commands

Examples

# Create a new note with markdown formatting
Create a note titled "Meeting Minutes" with content "# Discussion Points\n- Project timeline\n- Budget review\n- Next steps" and format headings and lists

# Create a note with HTML
Create a note titled "Formatted Report" with HTML content "<h1>Quarterly Report</h1><p>Sales increased by <strong>15%</strong></p>"

# List notes
Show me all my notes in the "Work" folder

# Get a specific note
Show me my note titled "Shopping List"

# Search notes
Find notes containing "recipe" in my "Cooking" folder

Pages Documents

Available Commands

Examples

# Create a new Pages document
Create a Pages document with the content "Project Proposal\n\nThis document outlines the scope and timeline for the upcoming project."

Debugging

Using MCP Inspector

The MCP Inspector provides a web interface for testing and debugging:

npm run inspector

or

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

Enabling Debug Logging

DEBUG=applescript-mcp* npm start

Common Issues

• Permission Errors: Check System Preferences > Security & Privacy > Privacy > Automation
• Script Failures: Test scripts directly in Script Editor.app before integration
• Communication Issues: Check stdio streams aren't being redirected
• Database Access: Some features (like Messages) require Full Disk Access permission

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.