AppleScript MCP server

The AppleScript MCP server is a powerful tool that lets you interact with macOS applications and system functions through AppleScript commands. This server implements the Model Context Protocol (MCP), allowing AI assistants like Claude to execute AppleScript on your Mac with minimal setup required.

Installation Options

Node.js Installation

The simplest way to install and use the AppleScript MCP server is through npm:

npm install @peakmojo/applescript-mcp

Python Installation

To install using Python with uv:

brew install uv
git clone https://github.com/path-to-applescript-mcp-repo

Configuration

Setting Up with Claude Desktop

Node.js Configuration

Add this to your Claude Desktop configuration:

{
  "mcpServers": {
    "applescript_execute": {
      "command": "npx",
      "args": [
        "@peakmojo/applescript-mcp"
      ]
    }
  }
}

Python Configuration

For Python implementation, use this configuration:

{
  "mcpServers": {
    "applescript_execute": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/repo",
        "run",
        "src/applescript_mcp/server.py"
      ]
    }
  }
}

Docker Configuration

When running in a Docker container, you can connect to your Mac host:

{
  "mcpServers": {
    "applescript_execute": {
      "command": "npx",
      "args": [
        "@peakmojo/applescript-mcp",
        "--remoteHost", "host.docker.internal",
        "--remoteUser", "yourusername",
        "--remotePassword", "yourpassword"
      ]
    }
  }
}

For Docker usage, ensure that:

• SSH is enabled on your Mac (System Settings → Sharing → Remote Login)
• Your user has proper permissions
• You provide the correct credentials in the configuration

Usage Examples

The AppleScript MCP server allows you to execute a wide range of AppleScript commands to interact with your Mac. Here are some examples of what you can do:

Managing Reminders and Calendar

Create a reminder for me to call John tomorrow at 10am

Add a new meeting to my calendar for Friday from 2-3pm titled "Team Review"

Working with Notes

Create a new note titled "Meeting Minutes" with today's date

File Operations

Show me all files in my Downloads folder from the past week

Create a folder on my Desktop named "Project Files"

System Information

What's my current battery percentage?

Tell me how much free space I have on my main drive

List all the currently running applications on my Mac

Application Control

Open Safari and navigate to apple.com

Play my "Focus" playlist in Apple Music

Communications

Show me the most recent unread emails in my inbox

Find John Smith in my contacts and show me his phone number

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.