MCP-AppleScript

Provides a local MCP server bridging Model Context Protocol to macOS AppleScript automation, exposing AppleScript tools.

typescript

0

GitHub Stars

typescript

Language

4 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "frouaix-mcpapplescript": {
      "command": "mcp-applescript",
      "args": []
    }
  }
}

You run a local MCP server that bridges the Model Context Protocol to macOS automation via AppleScript, exposing safe, policy-driven tools to MCP clients on your Mac.

How to use

Start the MCP AppleScript server and connect using your MCP client. You will access a suite of AppleScript-enabled tools organized by operation mode. Begin in readonly mode to explore available apps and actions, then gradually enable creation and full operations as needed. The server notifies your client when tool sets change, so you always know which actions you can perform in the current mode. Use the tools to list containers, inspect items, create new items, perform app-specific actions, or run raw AppleScript when you have explicit permission.

How to install

Prerequisites: macOS 12.0 or later, Node.js 20 or newer (for building from source), Swift 5.9 or newer (for building from source), and pnpm 8 or newer (for building from source). Choose one installation path below.

Option 1: Install a pre-built binary

Download the latest pre-built .dmg containing the MCP AppleScript server.
Open the .dmg and copy the executable to your bin directory.
Create a configuration file at your home configuration path.

mkdir -p ~/.config/applescript-mcp
cat > ~/.config/applescript-mcp/config.json << 'EOF'
{
  "defaultMode": "readonly",
  "apps": {
    "com.apple.Notes": { "enabled": true },
    "com.apple.iCal": { "enabled": true },
    "com.apple.reminders": { "enabled": true },
    "com.apple.mail": { "enabled": true },
    "com.apple.Contacts": { "enabled": true }
  }
}
EOF

Option 2: Build from source

Clone the repository, install dependencies, build, and install the Swift executor as described.

git clone https://github.com/frouaix/MCPAppleScript.git
cd MCPAppleScript
./install.sh

Claude Desktop integration

Optionally integrate with Claude Desktop by adding an MCP server entry that points to the local binary.

{
  "mcpServers": {
    "applescript": {
      "command": "/usr/local/bin/mcp-applescript"
    }
  }
}

Available tools

applescript.ping

Health check — returns server version and supported apps.

applescript.get_mode

Get current operation mode and enabled tools.

applescript.set_mode

Change operation mode (readonly/create/full).

app.list_containers

List containers such as folders, calendars, mailboxes, playlists, etc.

app.list

List items in a container with pagination.

app.get

Get a single item by ID.

app.search

Search or filter items.

app.create

Create a new item.

app.action

App-specific actions (send, play, complete, do_javascript, etc.).

applescript.run_template

Execute a registered template by ID (policy-gated).

app.update

Update an item (confirmation required).

app.delete

Delete an item (confirmation required).

applescript.run_script

Execute raw AppleScript (confirmation required).