MCP AppleScript MCP Server

MCP AppleScript

An MCP (Model Context Protocol) server that enables Large Language Models to execute AppleScript commands on macOS. This allows LLMs to interact with and automate macOS applications through natural language requests.

Features

• Execute AppleScript commands from LLM applications
• Application allowlist for controlled access to specific apps
• Dangerous pattern detection to block risky operations
• Configurable timeout protection
• Built on FastMCP for easy integration

Installation

Using uv:

uv pip install mcp-applescript

Or install from source:

git clone https://github.com/pietz/mcp-applescript.git
cd mcp-applescript
uv sync

Usage

Running the Server

mcp-applescript

The server runs using stdio transport, making it compatible with any MCP client.

Available Tools

`run_applescript`

Execute an AppleScript command on macOS.

Parameters:

• script (string): The AppleScript code to execute

Returns:

• String output from the script execution
• Raises error if script fails validation or execution

Example:

tell application "Mail"
    get subject of first message of inbox
end tell

`get_server_status`

Get the current server configuration and security settings.

Returns:

• Server version and configuration
• Allowed applications list
• Security settings (dangerous pattern blocking, timeout)
• Environment variable documentation

Example Response:

{
  "server": "MCP AppleScript",
  "version": "0.1.0",
  "security": {
    "allowed_apps": ["Mail", "Calendar"],
    "block_dangerous": true,
    "timeout_seconds": 30
  }
}

Configuration

MCP Client Setup

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "applescript": {
      "command": "mcp-applescript",
      "env": {
        "ALLOWED_APPS": "mail,calendar,contacts,notes",
        "BLOCK_DANGEROUS": "true"
      }
    }
  }
}

Environment Variables

ALLOWED_APPS (optional)

• Comma-separated list of allowed applications (case-insensitive)
• Example: "mail,calendar,contacts" (lowercase recommended)
• Not set (default): Allows all applications ("*")
• "*": Explicitly allows all applications
• "" (empty string): Blocks all applications (lockdown mode)
• Security Note: Set this to restrict access to specific apps only
• App names are automatically normalized to title case for AppleScript

BLOCK_DANGEROUS (optional)

• Enable/disable dangerous pattern detection
• Values: "true" or "false"
• Default: "true"
• Blocks patterns like: do shell script, file system access, system control commands

TIMEOUT (optional)

• Script execution timeout in seconds
• Default: "30"

Security Profiles

Default (Out of the Box)

"env": {
  // ALLOWED_APPS not set = allow all apps
  "BLOCK_DANGEROUS": "true"  // This is the default, can be omitted
}

• ✅ Works immediately without configuration
• ✅ Dangerous operations blocked
• ⚠️ Can access any application

Strict (Recommended for Production)

"env": {
  "ALLOWED_APPS": "mail,calendar,contacts",
  "BLOCK_DANGEROUS": "true"
}

• ✅ Limited to specific applications
• ✅ Dangerous operations blocked
• ✅ Best security posture

Permissive (Development/Testing Only)

"env": {
  "ALLOWED_APPS": "*",  // or omit this line
  "BLOCK_DANGEROUS": "false"
}

• ⚠️ Can access any application
• ⚠️ Dangerous operations allowed
• ⚠️ Use only in trusted environments

Lockdown (Explicit Block)

"env": {
  "ALLOWED_APPS": ""  // Empty string = block all
}

• 🔒 Blocks all AppleScript execution
• Useful for temporary disabling

Security

Built-in Protections

1. Application Allowlist (optional)

   • Default: All applications allowed (for usability)
   • Configure ALLOWED_APPS to restrict to specific applications
   • Prevents unauthorized access to system apps when configured

2. Dangerous Pattern Detection

   • Blocks shell command execution (do shell script)
   • Prevents system control operations (shutdown, restart, logout)
   • Blocks access to sensitive paths (/System, /Library, ~/.ssh)
   • Detects potential phishing (password dialogs)
   • Prevents file deletion operations

3. Execution Timeout

   • Prevents infinite loops and hanging scripts
   • Configurable timeout duration

Blocked Operations Examples

-- ❌ BLOCKED: Shell command execution
do shell script "rm -rf ~/"

-- ❌ BLOCKED: System control
tell application "System Events" to shut down

-- ❌ BLOCKED: Sensitive file access
do shell script "cat ~/.ssh/id_rsa"

-- ❌ BLOCKED: Unauthorized application (if not in ALLOWED_APPS)
tell application "Terminal" to do script "echo test"

-- ✅ ALLOWED: Reading from allowed app
tell application "Mail"
    get subject of first message of inbox
end tell

Best Practices

• **Configure application allowli