macOS Automator MCP

https://github.com/steipete/macos-automator-mcp
Admin
macOS Automator MCP is a Model Context Protocol (MCP) server that enables AI assistants to control...
Tokens:721,282
Snippets:4,028
Trust Score:10
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Start a Virtual Machine

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/13_developer/virtualbuddy/virtualbuddy_controller.md

Starts a virtual machine by name. It activates VirtualBuddy, finds the VM in the list, and clicks the 'Start' button. Includes error handling for cases where the VM or start button cannot be found.

```applescript
on startVirtualMachine(vmName)
    try
        tell application "VirtualBuddy" to activate
        delay 1
        
        -- Check if VM is already running
        if isVirtualMachineRunning(vmName) then
            display dialog "VM \"" & vmName & "\" is already running." buttons {"OK"} default button "OK" with icon note
            return
        end if
        
        tell application "System Events"
            tell process "VirtualBuddy"
                -- Find and select the VM in the list
                if exists table 1 of scroll area 1 of window 1 then
                    set vmRows to rows of table 1 of scroll area 1 of window 1
                    repeat with eachRow in vmRows
                        if value of text field 1 of eachRow as text is vmName then
                            select eachRow
                            exit repeat
                        end if
                    end repeat
                end if
                
                -- Try to find and click the Start button
                if exists button "Start" of window 1 then
                    click button "Start" of window 1
                else
                    -- Fallback: Try clicking the second button in the toolbar (often Start)
                    try
                        click button 2 of toolbar 1 of window 1
                    on error
                        display dialog "Could not find Start button for VM \"" & vmName & "\".
```

--------------------------------

### Start a Virtual Machine in VirtualBuddy

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/13_developer/virtualbuddy/virtualbuddy_automation.md

Handler to start a VM by name. It first checks if the VM is already running. If not, it selects the VM in the list and clicks the 'Start' button. Includes a fallback to try starting from the toolbar if the main button is not found.

```applescript
-- Handler to start a VM by name
on startVirtualMachine(vmName)
    try
        tell application "VirtualBuddy" to activate
        delay 1
        
        -- Check if VM is already running
        if isVirtualMachineRunning(vmName) then
            display dialog "VM \"" & vmName & "\" is already running." buttons {"OK"} default button "OK" with icon note
            return
        end if
        
        tell application "System Events"
            tell process "VirtualBuddy"
                -- Find and select the VM in the list
                if exists table 1 of scroll area 1 of window 1 then
                    set vmRows to rows of table 1 of scroll area 1 of window 1
                    repeat with eachRow in vmRows
                        if value of text field 1 of eachRow as text is vmName then
                            select eachRow
                            exit repeat
                        end if
                    end repeat
                end if
                
                -- Click the "Start" button
                if exists button "Start" of window 1 then
                    click button "Start" of window 1
                    display dialog "Starting VM \"" & vmName & "\"..." buttons {"OK"} default button "OK" with icon note
                else
                    -- Try secondary method - click Start from toolbar
                    try
                        click button 1 of toolbar 1 of window 1

```

--------------------------------

### Conceptual AppleScript Example

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/01_intro/meta_open_dictionary.md

This is a conceptual guide, not a runnable script. It demonstrates how to use information discovered in an application's dictionary to interact with its objects and properties.

```applescript
(*
  This is not a runnable script, but a conceptual guide.
  You would use the information found in a dictionary like this:
*)

-- After looking at Safari's dictionary, you might find:
-- Class: document
--   Properties:
--     URL (text) : The URL of the document.
--     name (text) : The title of the document.

-- So, you could write:
(*
tell application "Safari"
  if (count of documents) > 0 then
    set docName to name of front document
    set docURL to URL of front document
    display dialog "Page: " & docName & "\nURL: " & docURL
  end if
end tell
*)
```

--------------------------------

### Start Virtual Machine with VirtualBuddy

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/13_developer/virtualbuddy/virtualbuddy_controller.md

This handler starts a specified virtual machine by name. It first checks if the VM is already running. If not, it finds and selects the VM in the VirtualBuddy UI and clicks the 'Start' button. Includes a fallback for clicking the toolbar start button.

```applescript
-- Handler to start a VM by name
on startVirtualMachine(vmName)
    try
        tell application "VirtualBuddy" to activate
        delay 1
        
        -- Check if VM is already running
        if isVirtualMachineRunning(vmName) then
            display dialog "VM \"" & vmName & "\" is already running." buttons {"OK"} default button "OK" with icon note
            return
        end if
        
        tell application "System Events"
            tell process "VirtualBuddy"
                -- Find and select the VM in the list
                if exists table 1 of scroll area 1 of window 1 then
                    set vmRows to rows of table 1 of scroll area 1 of window 1
                    repeat with eachRow in vmRows
                        if value of text field 1 of eachRow as text is vmName then
                            select eachRow
                            exit repeat
                        end if
                    end repeat
                end if
                
                -- Click the "Start" button
                if exists button "Start" of window 1 then
                    click button "Start" of window 1
                    display dialog "Starting VM \"" & vmName & "\"..." buttons {"OK"} default button "OK" with icon note
                else
                    -- Try secondary method - click Start from toolbar
                    try
                        click button 1 of toolbar 1 of window 1
                        display dialog "Starting VM \"" & vmName & "\"..." buttons {"OK"} default button "OK" with icon note

```

--------------------------------

### Install brightness CLI Tool

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/04_system/display_control/system_display_brightness.md

Instructions for installing the `brightness` command-line tool using Homebrew.

```bash
brew install brightness
```

--------------------------------

### Example Usage of Audio Management Functions

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/04_system/system_preferences_settings/sound_output_input_selection.md

Demonstrates how to call the audio management functions, including listing devices, getting current configurations, and setting volume. Ensure the necessary functions like `listAudioDevices` and `getCurrentAudioDevices` are defined elsewhere in the script.

```applescript
-- Example usage
set deviceList to my listAudioDevices()
set currentDevices to my getCurrentAudioDevices()
-- set outputResult to my setAudioOutputDevice("MacBook Pro Speakers")
set volumeResult to my setOutputVolume(50, false)

return deviceList & return & return & currentDevices & return & return & volumeResult
```

--------------------------------

### Automate Project Workspace Setup in iTerm2

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/06_terminal/iterm/iterm_manage_titles.md

This AppleScript example demonstrates how to programmatically set up a project workspace in iTerm2, including creating windows, setting window titles, and creating/labeling tabs with specific directory changes.

```applescript
-- Example of setting up a complete project workspace
on setupProjectWorkspace(projectName, projectPath)
    tell application "iTerm2"
        create window with default profile

        -- Set window title to project name
        set name of current window to projectName

        -- Create and label tabs for different components
        tell current window
            -- First tab is already created
            tell current session of current tab
                set name to "Server"
                write text "cd " & quoted form of projectPath
            end tell

            -- Create tab for database
            set dbTab to (create tab with default profile)
            tell current session of dbTab
                set name to "Database"
                write text "cd " & quoted form of projectPath & "/database"
            end tell

            -- Create tab for frontend
            set frontendTab to (create tab with default profile)
            tell current session of frontendTab
                set name to "Frontend"
                write text "cd " & quoted form of projectPath & "/frontend"
            end tell
        end tell
    end tell
end setupProjectWorkspace
```

--------------------------------

### Complete AppleScript Clipboard Example

Source: https://github.com/steipete/macos-automator-mcp/blob/main/docs/applescript_clipboard.md

Demonstrates safely getting and setting clipboard content, including storing and restoring the original clipboard data to maintain user workflow.

```applescript
-- Store original clipboard to restore later
try
  set originalClip to the clipboard
on error
  set originalClip to ""
end try

-- Set new content
set the clipboard to "Test clipboard content"

-- Get the content back
set retrievedContent to the clipboard

-- Restore original content if we had any
try
  if originalClip is not "" then
    set the clipboard to originalClip
  end if
end try

return "Retrieved from clipboard: " & retrievedContent
```

--------------------------------

### Start Virtual Machine with AppleScript

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/13_developer/virtualbuddy/virtualbuddy_automation.md

Starts a specified VirtualBuddy VM. Ensures the VM is not already running before attempting to start. Handles potential errors during the process.

```applescript
on startVirtualMachine(vmName)
    try
        -- Check if VM is already running
        if isVirtualMachineRunning(vmName) then
            display dialog "VM \"" & vmName & "\" is already running." buttons {"OK"} default button "OK" with icon note
            return
        end if

        tell application "VirtualBuddy" to activate
        delay 1

        tell application "System Events"
            tell process "VirtualBuddy"
                -- Find and select the VM in the list
                if exists table 1 of scroll area 1 of window 1 then
                    set vmRows to rows of table 1 of scroll area 1 of window 1
                    repeat with eachRow in vmRows
                        if value of text field 1 of eachRow as text is vmName then
                            select eachRow
                            exit repeat
                        end if
                    end repeat
                end if

                -- Click the Start button (usually the first button in the toolbar)
                if exists button 1 of toolbar 1 of window 1 then
                    click button 1 of toolbar 1 of window 1
                else
                    display dialog "Could not find Start button for VM \"" & vmName & "\"." buttons {"OK"} default button "OK" with icon stop
                    return
                end if

                display dialog "Starting VM \"" & vmName & "..." buttons {"OK"} default button "OK" with icon note
            end tell
        end tell

    on error errMsg number errNum
        logError("Error starting VM: " & vmName, errMsg, errNum)
    end try
end startVirtualMachine
```

--------------------------------

### Start Virtual Machine by Name (AppleScript)

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/13_developer/virtualbuddy/virtualbuddy_automation.md

Starts a specified virtual machine in VirtualBuddy. It checks if the VM is already running, selects it in the list, and clicks the 'Start' button. Includes fallback logic for different UI element locations.

```applescript
on startVirtualMachine(vmName)
    try
        tell application "VirtualBuddy" to activate
        delay 1

        -- Check if VM is already running
        if isVirtualMachineRunning(vmName) then
            display dialog "VM \"" & vmName & "\" is already running." buttons {"OK"} default button "OK" with icon note
            return
        end if

        tell application "System Events"
            tell process "VirtualBuddy"
                -- Find and select the VM in the list
                if exists table 1 of scroll area 1 of window 1 then
                    set vmRows to rows of table 1 of scroll area 1 of window 1
                    repeat with eachRow in vmRows
                        if value of text field 1 of eachRow as text is vmName then
                            select eachRow
                            exit repeat
                        end if
                    end repeat
                end if

                -- Click the "Start" button
                if exists button "Start" of window 1 then
                    click button "Start" of window 1
                    display dialog "Starting VM \"" & vmName & "\"..." buttons {"OK"} default button "OK" with icon note
                else
                    -- Try secondary method - click Start from toolbar
                    try
                        click button 1 of toolbar 1 of window 1
                        display dialog "Starting VM \"" & vmName & "\"..." buttons {"OK"} default button "OK" with icon note
                    on error
                        display dialog "Could not find Start button for VM \"" & vmName & "\"." buttons {"OK"} default button "OK" with icon stop
                    end try
                end if
            end tell
        end tell

    on error errMsg number errNum
        logError("Error starting VM: " & vmName, errMsg, errNum)
    end try
end startVirtualMachine
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/steipete/macos-automator-mcp/blob/main/docs/DEVELOPMENT.md

Install all necessary project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Install Dependencies with npm

Source: https://github.com/steipete/macos-automator-mcp/blob/main/CLAUDE.md

Installs project dependencies using npm. This is a standard first step for setting up the project.

```bash
npm install
```

--------------------------------

### Install Local CLI Globally

Source: https://github.com/steipete/macos-automator-mcp/blob/main/docs/DEVELOPMENT.md

Install the local command-line interface globally using pnpm.

```bash
pnpm add --global .
```

--------------------------------

### Start Virtual Machine (AppleScript)

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/13_developer/virtualbuddy/virtualbuddy_controller.md

Starts a specified virtual machine by name. It checks if the VM is already running and handles potential UI element variations for the 'Start' button. Requires VirtualBuddy to be running.

```applescript
on startVirtualMachine(vmName)
    try
        tell application "VirtualBuddy" to activate
        delay 1

        -- Check if VM is already running
        if isVirtualMachineRunning(vmName) then
            display dialog "VM \"" & vmName & "\" is already running." buttons {"OK"} default button "OK" with icon note
            return
        end if

        tell application "System Events"
            tell process "VirtualBuddy"
                -- Find and select the VM in the list
                if exists table 1 of scroll area 1 of window 1 then
                    set vmRows to rows of table 1 of scroll area 1 of window 1
                    repeat with eachRow in vmRows
                        if value of text field 1 of eachRow as text is vmName then
                            select eachRow
                            exit repeat
                        end if
                    end repeat
                end if

                -- Click the "Start" button
                if exists button "Start" of window 1 then
                    click button "Start" of window 1
                    display dialog "Starting VM \"" & vmName & "\"..." buttons {"OK"} default button "OK" with icon note
                else
                    -- Try secondary method - click Start from toolbar
                    try
                        click button 1 of toolbar 1 of window 1
                        display dialog "Starting VM \"" & vmName & "\"..." buttons {"OK"} default button "OK" with icon note
                    on error
                        display dialog "Could not find Start button for VM \"" & vmName & "\"" buttons {"OK"} default button "OK" with icon stop
                    end try
                end if
            end tell
        end tell

    on error errMsg number errNum
        logError("Error starting VM: " & vmName, errMsg, errNum)
    end try
end startVirtualMachine
```

--------------------------------

### Install and Launch App on iOS Simulator

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/13_developer/xcode_app/ios_simulator_install_app.md

Use this AppleScript to install an app bundle to a specified simulator device. It can target a specific device by name or UDID, or use 'booted' for the currently active device. The app can optionally be launched after installation. The script returns the bundle identifier of the installed app.

```applescript
--MCP_INPUT:appPath
--MCP_INPUT:deviceIdentifier
--MCP_INPUT:launchAfterInstall

on installAppOnSimulator(appPath, deviceIdentifier, launchAfterInstall)
  if appPath is missing value or appPath is "" then
    return "error: App path not provided. Specify a path to a .app bundle built for simulator."
  end if

  if deviceIdentifier is missing value or deviceIdentifier is "" then
    set deviceIdentifier to "booted"
  end if

  -- Default to launching after install unless explicitly set to false
  if launchAfterInstall is missing value or launchAfterInstall is "" then
    set launchAfterInstall to true
  else if launchAfterInstall is "false" then
    set launchAfterInstall to false
  end if

  try
    -- Ensure the app exists
    set checkAppCmd to "test -d " & quoted form of appPath & " && echo 'exists' || echo 'not found'"
    set appExistsResult to do shell script checkAppCmd

    if appExistsResult is "not found" then
      return "error: App not found at path: " & appPath
    end if

    -- Check if the app path ends with .app
    if not (appPath ends with ".app") then
      return "error: The provided path does not appear to be an app bundle (should end with .app): " & appPath
    end if

    -- Extract the bundle identifier from the app's Info.plist
    set bundleIdCmd to "defaults read " & quoted form of appPath & "/Info CFBundleIdentifier"
    set bundleId to do shell script bundleIdCmd

    -- Check if the device exists or is booted
    if deviceIdentifier is not "booted" then
      set checkDeviceCmd to "xcrun simctl list devices | grep '" & deviceIdentifier & "'"
      try
        do shell script checkDeviceCmd
      on error
        return "error: Device '" & deviceIdentifier & "' not found. Use 'booted' for the currently booted device, or check available devices."
      end try
    end if

    -- Install the app
    set installCmd to "xcrun simctl install " & quoted form of deviceIdentifier & " " & quoted form of appPath
    try
      do shell script installCmd
      set installSuccessful to true
    on error errMsg
      return "error: Failed to install app: " & errMsg
    end try

    -- Launch the app if requested
    set launchResult to ""
    if launchAfterInstall and installSuccessful then
      try
        set launchCmd to "xcrun simctl launch " & quoted form of deviceIdentifier & " " & bundleId
        set launchOutput to do shell script launchCmd
        set launchResult to "
App launched successfully. " & launchOutput
      on error errMsg
        set launchResult to "
App installed but launch failed: " & errMsg
      end try
    end if

    return "Successfully installed app '" & bundleId & "' on " & deviceIdentifier & " simulator device." & launchResult & "

App path: " & appPath & "
Bundle identifier: " & bundleId
  on error errMsg number errNum
    return "error (" & errNum & ") installing app on iOS simulator: " & errMsg
  end try
end installAppOnSimulator

return my installAppOnSimulator("--MCP_INPUT:appPath", "--MCP_INPUT:deviceIdentifier", "--MCP_INPUT:launchAfterInstall")
```

--------------------------------

### Install switchaudio-osx via Homebrew

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/04_system/system_preferences_settings/sound_output_input_selection.md

This command installs the `switchaudio-osx` command-line tool using Homebrew, which is recommended for reliable audio device switching on macOS.

```bash
brew install switchaudio-osx
```

--------------------------------

### Install a Sublime Text Package

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/08_editors/sublime_text/sublime_text_package_management.md

Initiates the package installation process in Sublime Text. It opens the command palette, selects 'Package Control: Install Package', and prompts the user to manually select the desired package from the search results.

```applescript
on installPackage(packageName)
    tell application "System Events"
        tell process "Sublime Text"
            -- Open command palette
            keystroke "p" using {command down, shift down}
            delay 0.3

            -- Type "Package Control: Install Package"
            keystroke "Package Control: Install Package"
            delay 0.3

            -- Execute the command
            keystroke return

            -- Wait for the package list to load
            delay 2

            -- Type the package name
            keystroke packageName
            delay 0.5

            -- Wait for search results to narrow down
            -- At this point, the user needs to select the specific package and press Return
            -- Since we can't programmatically determine which package is the correct one in the list,
            -- we'll provide instructions to the user
        end tell
    end tell

    return "Package search executed for '" & packageName & "'. Please select the package from the list and press Return to install."
end installPackage
```

--------------------------------

### Start Compiled Server

Source: https://github.com/steipete/macos-automator-mcp/blob/main/CLAUDE.md

Starts the server after the project has been built. This command is typically used for running the production version of the server.

```bash
npm run start
```

--------------------------------

### Get All To-Dos from Things

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/13_developer/things/things_get_todos.md

Retrieves all to-dos from the Things app. Ensure Things 3 is installed.

```applescript
-- Get all to-dos
tell application "Things3"
    set allToDos to to dos
    log (count of allToDos) & " to-dos found"
end tell
```

--------------------------------

### Start the Server using start.sh

Source: https://github.com/steipete/macos-automator-mcp/blob/main/docs/DEVELOPMENT.md

Execute the start.sh script to run the server locally.

```bash
./start.sh
```

--------------------------------

### Get UI Hierarchy Starting from a Specific Element

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/03_jxa_core/ui_automation/jxa_ui_hierarchy.md

Explore the UI hierarchy starting from a particular UI element within an application. Specify the application name and a target object with its role and name.

```json
{
  "action": "getUIHierarchy",
  "appName": "Safari",
  "target": {
    "role": "AXButton",
    "name": "Back"
  }
}
```

--------------------------------

### Initialize CSV and Sample Process

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/13_developer/xcode_app/ios_simulator_performance_report.md

Sets up the CSV file header and begins sampling the application's process statistics at a defined interval. Handles cases where the process might terminate.

```bash
echo "Timestamp,CPU %,Memory %,RSS (KB),VSZ (KB),State,Runtime" > "$OUTPUT_DIR/performance.csv"

for ((i=1; i<=$SAMPLE_COUNT; i++)); do
    TIMESTAMP=$(date +"%Y-%m-%d %H:%M:%S")

    STATS=$(get_process_stats $APP_PID)

    if [ -z "$STATS" ]; then
        APP_PID=$(xcrun simctl spawn $DEVICE ps aux | grep "$BUNDLE_ID" | grep -v grep | awk '{print $2}' | head -1)
        if [ -z "$APP_PID" ]; then
            echo "Warning: App process terminated during monitoring at sample $i"
            break
        fi
        STATS=$(get_process_stats $APP_PID)
    fi

    PID=$(echo "$STATS" | awk '{print $1}')
    CPU=$(echo "$STATS" | awk '{print $2}')
    MEM=$(echo "$STATS" | awk '{print $3}')
    RSS=$(echo "$STATS" | awk '{print $4}')
    VSZ=$(echo "$STATS" | awk '{print $5}')
    STATE=$(echo "$STATS" | awk '{print $6}')
    TIME=$(echo "$STATS" | awk '{print $7}')

    echo "$TIMESTAMP,$CPU,$MEM,$RSS,$VSZ,$STATE,$TIME" >> "$OUTPUT_DIR/performance.csv"

    if [ $((i % 5)) -eq 0 ] || [ $i -eq 1 ] || [ $i -eq $SAMPLE_COUNT ]; then
        echo "Sample $i/$SAMPLE_COUNT: CPU: ${CPU}%, Memory: ${MEM}%, RSS: ${RSS}KB"
    fi

    if [ $i -lt $SAMPLE_COUNT ]; then
        sleep 1
    fi
done
```

--------------------------------

### Example: Create a file with content

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/06_terminal/file_operations/terminal_create_file.md

Provide both the destination path and the desired content in JSON format to create a file with initial text.

```json
{
  "destination": "/Users/username/Documents/config.json",
  "content": "{\n  \"name\": \"My App\",\n  \"version\": \"1.0.0\"\n}"
}
```

--------------------------------

### Get All System Information Summary

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/04_system/system_info/system_information_retrieval.md

Aggregates information from all other system info retrieval functions into a single summary. This is an example usage function.

```applescript
-- Example usage: Get all system information
on getAllSystemInfo()
  set osInfo to getOSVersion()
  set hwInfo to getHardwareInfo()
  set storageInfo to getStorageInfo()
  set networkInfo to getNetworkInfo()
  set batteryInfo to getBatteryInfo()

  -- Format a summary of the information
  set summary to "System Information Summary:" & return & return

  -- OS Info

```

--------------------------------

### Example: Get Value of Text Field

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/03_jxa_core/ui_automation/jxa_ui_element_values.md

Demonstrates how to use the getValue action with specific parameters for targeting a text area in the Notes application.

```json
{
  "action": "getValue",
  "appName": "Notes",
  "target": {
    "elementType": "textAreas",
    "index": 0
  }
}
```

--------------------------------

### Get To-Dos from a Specific List in Things

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/13_developer/things/things_get_todos.md

Retrieves to-dos from a specific list, such as 'Today', within the Things app. Ensure Things 3 is installed.

```applescript
-- Get to-dos from a specific list
tell application "Things3"
    set todayToDos to to dos of list "Today"
    log (count of todayToDos) & " to-dos for today"
end tell
```

--------------------------------

### Choose URL with StandardAdditions

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/02_as_core/scripting_additions_osax/osax_choose_url.md

This example demonstrates how to use the `choose URL` command to prompt the user for a website URL and a local file URL. It includes error handling for user cancellation.

```applescript
set chosenURL to ""
try
  -- Choose a URL, showing HTTP/HTTPS field by default
  set urlResult to choose URL with prompt "Enter the website URL:" with title "Website Chooser"
  if urlResult is not false then
    set chosenURL to "URL: " & urlResult
  else
    set chosenURL to "User cancelled URL input."
  end if

  -- Choose a File URL
  set fileURLResult to choose URL showing File with prompt "Select a local file to get its URL:" with title "File URL Chooser"
  if fileURLResult is not false then
    set chosenURL to chosenURL & "\nFile URL: " & fileURLResult
  else
    set chosenURL to chosenURL & "\nUser cancelled File URL input."
  end if

on error errMsg number errNum
  if errNum is -128 then
    set chosenURL to chosenURL & "\nUser cancelled a dialog (-128)."
  else
    set chosenURL to chosenURL & "\nError (" & errNum & "): " & errMsg
  end if
end try

return chosenURL
```

--------------------------------

### Get To-Dos with a Specific Tag in Things

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/13_developer/things/things_get_todos.md

Retrieves to-dos that are associated with a specific tag, like 'Work', from the Things app. Ensure Things 3 is installed.

```applescript
-- Get to-dos with a specific tag
tell application "Things3"
    set workToDos to to dos where tag names contains "Work"
    log (count of workToDos) & " work-related to-dos"
end tell
```

--------------------------------

### Setup Kaleidoscope as Git Diff Tool

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/13_developer/kaleidoscope/kaleidoscope_dev_tools_integration.md

Configures Git to use Kaleidoscope for diffing and merging. It checks for 'ksdiff' installation and sets global Git configurations.

```applescript
-- Setup Kaleidoscope as the diff tool for Git
on setupAsGitDiffTool()
    try
        -- Check if ksdiff is installed
        set ksdiffPath to do shell script "which ksdiff || echo 'not found'"

        if ksdiffPath contains "not found" then
            -- Try common installation locations
            if (do shell script "[ -f /usr/local/bin/ksdiff ] && echo 'exists' || echo 'not exists'") contains "exists" then
                set ksdiffPath to "/usr/local/bin/ksdiff"
            else if (do shell script "[ -f /opt/homebrew/bin/ksdiff ] && echo 'exists' || echo 'not exists'") contains "exists" then
                set ksdiffPath to "/opt/homebrew/bin/ksdiff"
            else
                return "Error: ksdiff command-line tool not found. Please install Kaleidoscope and its CLI tools."
            end if
        end if

        -- Configure Git to use Kaleidoscope
        do shell script "git config --global diff.tool Kaleidoscope"
        do shell script "git config --global difftool.Kaleidoscope.cmd '" & ksdiffPath & " --diff \"$LOCAL\" \"$REMOTE\"'"
        do shell script "git config --global merge.tool Kaleidoscope"
        do shell script "git config --global mergetool.Kaleidoscope.cmd '" & ksdiffPath & " --merge --output \"$MERGED\" \"$LOCAL\" \"$BASE\" \"$REMOTE\"'"
        do shell script "git config --global mergetool.Kaleidoscope.trustExitCode true"

        return "Kaleidoscope has been set up as the default Git diff and merge tool."
    on error errMsg
        return "Error configuring Git: " & errMsg
    end try
end setupAsGitDiffTool
```

--------------------------------

### Example: Create file in new directory

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/06_terminal/file_operations/terminal_create_file.md

This example demonstrates creating a file within a directory structure that does not yet exist. The script will automatically create the necessary parent directories.

```json
{
  "destination": "/Users/username/NewProject/src/index.js",
  "content": "console.log('Hello, World!');"
}
```

--------------------------------

### Compare Clipboard with File in Kaleidoscope

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/13_developer/kaleidoscope/kaleidoscope_compare_clipboard.md

This is a direct example of how to use Kaleidoscope's URL scheme to compare the clipboard with a file. Ensure Kaleidoscope is installed and the file path is correct.

```applescript
-- Compare clipboard with a specific file
open location "kaleidoscope://clipboard?/path/to/file.txt&label=Clipboard Comparison"
```

--------------------------------

### Example MCP Script Calls

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/09_productivity/home_app/home_manage_automations.md

These examples demonstrate how to call the `manageHomeAutomations` script using MCP (presumably a scripting or automation framework). They show the input data structure for listing, enabling, and disabling automations.

```mcp
-- Example of calling with MCP
-- Get list of all automations:
-- execute_script(id="home_manage_automations", inputData={action:"list"})
-- Enable a specific automation:
-- execute_script(id="home_manage_automations", inputData={action:"enable", automationName:"Morning Lights"})
-- Disable a specific automation:
-- execute_script(id="home_manage_automations", inputData={action:"disable", automationName:"Evening Lights"})
```

--------------------------------

### Get Safari Bookmarks with Folder Filter

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/07_browsers/safari/safari_get_bookmarks.md

Retrieves Safari bookmarks, optionally filtering by a specific folder name. Handles cases where the bookmarks database is not found. Requires Safari to be installed.

```applescript
--MCP_INPUT:folderName

on getSafariBookmarks(folderName)
  set bookmarksDbPath to (POSIX path of (path to home folder)) & "Library/Safari/Bookmarks.plist"

  -- Check if the database exists
  set dbExists to do shell script "[ -f " & quoted form of bookmarksDbPath & " ] && echo 'yes' || echo 'no'"

  if dbExists is "no" then
    return "error: Safari bookmarks database not found. Make sure Safari has been run at least once."
  end if

  -- Use plutil to convert plist to JSON and then parse it
  set jsonData to do shell script "plutil -convert json -o - " & quoted form of bookmarksDbPath

  -- Use shell script with Python to extract bookmarks from JSON
  set pythonScript to "
import sys
import json
import os

# Parse JSON
data = json.loads(sys.stdin.read())

# Function to process bookmark items recursively
def process_bookmark_items(items, folder_filter=None, current_folder=''):
    result = []

    for item in items:
        if item.get('WebBookmarkType') == 'WebBookmarkTypeList':
            # This is a folder
            folder_name = item.get('Title', 'Untitled Folder')
            folder_path = current_folder + '/' + folder_name if current_folder else folder_name

            # Process children of this folder
            children = item.get('Children', [])
            child_results = process_bookmark_items(children, folder_filter, folder_path)

            # Add folder entry with its children
            if child_results and (folder_filter is None or folder_filter.lower() in folder_path.lower()):
                result.append({
                    'type': 'folder',
                    'title': folder_name,
                    'path': folder_path,
                    'items': child_results
                })
        elif item.get('WebBookmarkType') == 'WebBookmarkTypeLeaf':
            # This is a bookmark
            url = item.get('URLString', '')
            title = item.get('URIDictionary', {}).get('title', 'Untitled')

            if url and (folder_filter is None or folder_filter.lower() in current_folder.lower()):
                result.append({
                    'type': 'bookmark',
                    'title': title,
                    'url': url,
                    'path': current_folder
                })

    return result

# Get folder filter from environment variable if provided
folder_filter = os.environ.get('FOLDER_FILTER')

# Process all bookmarks
all_bookmarks = process_bookmark_items(data.get('Children', []), folder_filter)

# Print the result as JSON
print(json.dumps(all_bookmarks, indent=2))
"

  set pythonEnvVars to "FOLDER_FILTER='" & folderName & "'"
  set fullPythonCommand to "export FOLDER_FILTER='" & folderName & "'; " & pythonScript

  set extractedData to do shell script "echo 
```

--------------------------------

### Access File Properties with Finder

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/02_as_core/reference_forms/core_reference_property.md

Shows how to get properties like name, kind, and size of a file using the Finder application. This example is commented out by default and requires the Finder to be accessible.

```applescript
-- File properties (using Finder)
set fileInfo to "(Finder example not run by default / TextEdit.app example)"
(*
tell application "Finder"
  try
    set appPath to (path to application "TextEdit")
    set appFile to file (POSIX path of appPath) -- More direct way to get Finder item for app

    set appName to name of appFile
    set appKind to kind of appFile
    set appSize to size of appFile
    set fileInfo to "App: " & appName & ", Kind: " & appKind & ", Size: " & appSize
  on error errMsg
    set fileInfo to "Finder error: " & errMsg
  end try
end tell*
)
```

--------------------------------

### Example Usage of setAppLaunchArguments

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/13_developer/xcode_app/ios_simulator_launch_arguments.md

Demonstrates calling the setAppLaunchArguments function with specific parameters for bundle ID, launch arguments, environment variables, and device identifier.

```applescript
return my setAppLaunchArguments("--MCP_INPUT:bundleID", "--MCP_INPUT:launchArgs", "--MCP_INPUT:environmentVars", "--MCP_INPUT:deviceIdentifier")
```

--------------------------------

### Advanced VM Operations in Parallels Desktop

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/13_developer/parallels_desktop/parallels_desktop_vm_controller.md

Performs advanced operations on a virtual machine, such as retrieving CPU and memory configuration. Includes commented-out examples for taking screenshots and getting network information.

```applescript
-- Advanced VM operations (could be expanded)
on advancedVMOperations(vmName)
try
    tell application "Parallels Desktop"
        set targetVM to virtual machine vmName

        -- Examples of advanced operations:

        -- 1. Get VM configuration properties
        set vmCPU to cpu count of configuration of targetVM
        set vmMemory to memory size of configuration of targetVM

        -- 2. Take a screenshot of the VM
        -- set screenshotPath to (path to desktop folder as text) & "vm_screenshot.png"
        -- execute command "screencapture -x " & screenshotPath in targetVM

        -- 3. Get VM network information
        -- set vmIPAddress to execute command "ipconfig getifaddr en0" in targetVM

        return "VM Configuration:" & return & "CPU: " & vmCPU & " cores" & return & "Memory: " & vmMemory & " MB"
    end tell
on error errMsg
    log "Failed to perform advanced operations on '" & vmName & "': " & errMsg
    return "Error: " & errMsg
end try
end advancedVMOperations
```

--------------------------------

### Run the Server in Development Mode

Source: https://github.com/steipete/macos-automator-mcp/blob/main/docs/DEVELOPMENT.md

Start the server in development mode using the pnpm script.

```bash
pnpm run dev
```

--------------------------------

### Get Volume for App via Sound Control

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/04_system/audio_control/app_specific_volume.md

Retrieve the current volume and mute status for a specified application using the Sound Control application. This requires Sound Control to be installed and running.

```applescript
try
      tell application "Sound Control"
        set apps to audio apps
        repeat with anApp in apps
          if id of anApp contains appNameParam then
            set appVolume to volume of anApp
            set appMuted to muted of anApp

            set resultText to "Current volume for '" & appNameParam & "' (via Sound Control): " & (appVolume * 100) & "%"
            if appMuted then
              set resultText to resultText & " (muted)"
            end if

            return resultText
          end if
        end repeat
      end tell

      return "Could not find '" & appNameParam & "' in Sound Control's audio apps."
    on error errMsg
      return "Error getting volume via Sound Control: " & errMsg
    end try
```

--------------------------------

### Get All UI Elements of a Specific Type

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/03_jxa_core/system_events/jxa_ui_elements_control.md

Provides examples for retrieving all elements of a certain type (buttons, text fields, checkboxes) from the frontmost window of a process. Useful for iterating through or inspecting available controls.

```javascript
// Get all buttons in the front window
const buttons = process.windows[0].buttons();

// Get all text fields in the front window
const textFields = process.windows[0].textFields();

// Get all checkboxes in the front window
const checkboxes = process.windows[0].checkboxes();
```

--------------------------------

### Execute AppleScript File with Parameters

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/02_as_core/scripting_additions_osax/osax_run_script.md

Demonstrates how to create a target AppleScript file, compile it, and then execute it using `run script` with parameters. Includes error handling and cleanup.

```applescript
-- Setup: Create a simple script file to be run
set desktopPath to path to desktop
set targetScriptPath to (desktopPath as text) & "TargetScript.scpt"
set targetScriptContent to "on run {name, count}\n  set message to \"Hello, \" & name & \"! You ran this \" & count & \" times.\"\n  return message\nend run"

try
  set fRef to open for access file targetScriptPath with write permission
  set eof fRef to 0
  write targetScriptContent to fRef
  close access fRef
  -- For `run script` with a file, it should be compiled.
  -- `store script` will compile it.
  set tempScriptObj to script
    on run {name, count}
      set message to "Hello, " & name & "! You ran this " & count & " times."
      return message
    end run
  end script
  store script tempScriptObj in file targetScriptPath replacing yes
on error e
  return "Error creating target script: " & e
end try

set result1 to ""
set result2 to ""

-- 1. Run script from file with parameters
try
  set scriptFileAlias to alias targetScriptPath
  set result1 to run script scriptFileAlias with parameters {"Alice", 1}
on error e
  set result1 to "Error running script from file: " & e
end try

-- 2. Run a script object directly
set myScriptObject to script
  property greeting : "Hola"
  on wave(person)
    return greeting & " " & person & ", *waves*"
  end wave
  on run {arg1}
    return "Script object ran with: " & arg1
  end run
end script

try
  -- To run the 'run' handler of the script object:
  set result2_run to run script myScriptObject with parameters {"Direct Param"}
  -- To run a specific handler from the script object:
  set result2_wave to wave("Bob") of myScriptObject
  set result2 to result2_run & "\n" & result2_wave
on error e
  set result2 to "Error running script object: " & e
end try

-- Clean up the created script file (optional)
try
  tell application "Finder" to delete file targetScriptPath
on error
  -- ignore cleanup error
end try

return "Result from file: " & result1 & "\n\nResult from object: " & result2
```

--------------------------------

### Parallels Desktop VM Management Script

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/13_developer/parallels_desktop/parallels_desktop_vm_management.md

This AppleScript provides functions to manage Parallels Desktop virtual machines. It handles listing, starting, stopping, suspending, and checking the status of VMs. Ensure Parallels Desktop is installed and accessible.

```applescript
-- Parallels Desktop VM Management
-- This script demonstrates various operations with Parallels Desktop virtual machines
-- Operations: list, start, stop, suspend, status

on run {vmName, operation}
	-- Set default values if parameters are not provided
	if vmName is missing value then set vmName to "--MCP_INPUT:vmName"
	if operation is missing value then set operation to "--MCP_INPUT:operation"

	-- Validate operation parameter
	set validOperations to {"list", "start", "stop", "suspend", "status"}
	if operation is not in validOperations then
		return "Error: Invalid operation. Please use one of: " & validOperations as string
	end if

	-- Main control flow based on the requested operation
	try
		if operation is "list" then
			return listVirtualMachines()
		else if operation is "status" then
			return getVMStatus(vmName)
		else if operation is "start" then
			return startVM(vmName)
		else if operation is "stop" then
			return stopVM(vmName)
		else if operation is "suspend" then
			return suspendVM(vmName)
		end if
	on error errMsg
		return "Error: " & errMsg
	end try
end run

-- Lists all available virtual machines
on listVirtualMachines()
	try
		tell application "Parallels Desktop"
			set vmList to {}
			set allVMs to every virtual machine

			repeat with currentVM in allVMs
				set vmName to name of currentVM
				set vmState to state of currentVM as string
				set end of vmList to vmName & " (" & vmState & ")"
			end repeat

			if length of vmList is 0 then
				return "No virtual machines found."
			else
				return "Available virtual machines:" & linefeed & (vmList as string)
			end if
		end tell
	on error errMsg
		return "Failed to list virtual machines: " & errMsg
	end try
end listVirtualMachines

-- Checks if the specified VM exists
on vmExists(vmName)
	try
		tell application "Parallels Desktop"
			set allVMs to every virtual machine
			repeat with currentVM in allVMs
				if name of currentVM is vmName then
					return true
				end if
			end repeat
		end tell
		return false
	on error
		return false
	end try
end vmExists

-- Gets the current status of a VM
on getVMStatus(vmName)
	if not vmExists(vmName) then
		return "Error: Virtual machine '" & vmName & "' does not exist."
	end if

	try
		tell application "Parallels Desktop"
			set targetVM to virtual machine vmName
			set vmState to state of targetVM as string
			return "Virtual machine '" & vmName & "' is currently " & vmState & "."
		end tell
	on error errMsg
		return "Failed to get status for '" & vmName & "': " & errMsg
	end try
end getVMStatus

-- Starts a VM
on startVM(vmName)
	if not vmExists(vmName) then
		return "Error: Virtual machine '" & vmName & "' does not exist."
	end if

	try
		tell application "Parallels Desktop"
			set targetVM to virtual machine vmName

			-- Only start if not already running
			if state of targetVM is not running then
				start targetVM
				return "Starting virtual machine '" & vmName & "'."
			else
				return "Virtual machine '" & vmName & "' is already running."
			end if
		end tell
	on error errMsg
		return "Failed to start '" & vmName & "': " & errMsg
	end try
end startVM

-- Stops a VM (power off)
on stopVM(vmName)
	if not vmExists(vmName) then
		return "Error: Virtual machine '" & vmName & "' does not exist."
	end if

	try
		tell application "Parallels Desktop"
			set targetVM to virtual machine vmName

			-- Only stop if running
			if state of targetVM is running then
				-- Using force stop (equivalent to power off)
				stop targetVM with force
				return "Stopping virtual machine '" & vmName & "'."
			else
				return "Virtual machine '" & vmName & "' is not running."
			end if
		end tell
	on error errMsg
		return "Failed to stop '" & vmName & "': " & errMsg
	end try
end stopVM

-- Suspends a VM (save state)
on suspendVM(vmName)
	if not vmExists(vmName) then
		return "Error: Virtual machine '" & vmName & "' does not exist."
	end if

	try
		tell application "Parallels Desktop"
			set targetVM to virtual machine vmName

			-- Only suspend if running
			if state of targetVM is running then
				suspend targetVM
				return "Suspending virtual machine '" & vmName & "'."
			else
				return "Virtual machine '" & vmName & "' is not running."
			end if
		end tell
	on error errMsg
		return "Failed to suspend '" & vmName & "': " & errMsg
	end try
end suspendVM

-- Advanced operations that could be added:
-- - Clone a VM
-- - Take a snapshot
-- - Restore from a snapshot
-- - Change VM configuration
-- - Execute commands inside the VM (requires guest tools)

```

--------------------------------

### Common Server Commands for Node.js Projects

Source: https://github.com/steipete/macos-automator-mcp/blob/main/knowledge_base/06_terminal/iterm/iterm_dev_environment.md

Use this command to start a Node.js project's server.

```bash
npm start
```
Tokens:
Raw