MacOS Automation Server

A comprehensive MCP (Model Context Protocol) server for macOS automation via AppleScript. This server provides 45 universal tools for system control, application management, calendar, reminders, notifications, clipboard operations, and scheduled tasks.

Built with FastMCP and Pydantic for type-safe, production-ready operation.

✅ Verified Working

• macOS 26.1+ compatible
• All 45 tools registered and functional
• AppleScript execution engine tested
• Shell command safety validation active

Features

P0 - Essential Tools (12 System + 6 App + 3 Notification + 3 Clipboard = 24 tools)

• System Control: Volume, dark mode, display sleep, WiFi, text-to-speech, screenshots
• Application Control: Launch, quit, list, and manage running applications
• Notifications: Send notifications, alerts, and dialogs
• Clipboard: Read, write, and manage clipboard contents

P1 - Extended Tools (6 Finder + 3 Calendar + 5 Reminders = 14 tools)

• Finder Operations: Create folders, move to trash, reveal files, search
• Calendar Integration: List, create, and manage calendar events
• Reminders Integration: List, create, complete, and manage reminders

P2 - Advanced Tools (4 Script + 3 Scheduler = 7 tools)

• Script Execution: Run AppleScript and shell commands
• Task Scheduler: Create and manage launchd scheduled tasks

Installation

Prerequisites

• macOS 10.15 or later
• Python 3.10 or later
• uv (recommended) or pip

Install with uv (Recommended)

cd /path/to/mcp-applescript-automation
uv sync

Install with pip

cd /path/to/mcp-applescript-automation
pip install -e .

Configuration

Claude Desktop / Cursor

Add to your MCP configuration file:

{
  "mcpServers": {
    "macos-automation": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-applescript-automation", "python", "main.py"],
      "env": {}
    }
  }
}

Minerva Platform

Add to config/mcp-servers.json:

"macos-automation-mcp": {
  "command": "uv",
  "args": ["run", "--directory", "/Volumes/dev-4tb/AA-GitHub/MCP/mcp-applescript-automation", "python", "main.py"],
  "env": {},
  "description": "macOS Automation MCP: System control, app management, calendar, reminders, notifications, scheduled tasks via AppleScript"
}

Permissions

This server requires certain macOS permissions to function:

1. Automation Permission (Required)

   • System Preferences > Privacy & Security > Privacy > Automation
   • Grant permission to your terminal app (Terminal, iTerm2, Cursor, etc.)

2. Accessibility Permission (For some UI automation)

   • System Preferences > Privacy & Security > Privacy > Accessibility
   • Required for advanced UI interactions

3. Calendar/Reminders Access (For calendar/reminder tools)

   • System Preferences > Privacy & Security > Privacy > Calendars/Reminders
   • Required for calendar and reminder management

Available Tools (45 Total)

System Control (12 tools)

Tool	Description
get_system_info	Get macOS version, hostname, user, and uptime
set_volume	Set system volume (0-100)
get_volume	Get current volume level
toggle_mute	Toggle audio mute
toggle_dark_mode	Toggle dark/light mode
set_dark_mode	Set dark mode explicitly
is_dark_mode	Check if dark mode is enabled
sleep_display	Put display to sleep
say_text	Speak text using TTS
take_screenshot	Capture screenshot
get_wifi_network	Get current WiFi network
toggle_wifi	Enable/disable WiFi

Application Control (6 tools)

Tool	Description
list_running_apps	List all running applications
get_frontmost_app	Get active application info
launch_app	Launch an application
quit_app	Quit an application
hide_app	Hide an application
is_app_running	Check if app is running

Notifications (3 tools)

Tool	Description
send_notification	Send macOS notification
send_alert	Show alert dialog
choose_from_list	Show selection dialog

Clipboard (3 tools)

Tool	Description
get_clipboard	Get clipboard text
set_clipboard	Copy text to clipboard
clear_clipboard	Clear clipboard

Finder (6 tools)

Tool	Description
reveal_in_finder	Reveal file in Finder
create_folder	Create new folder
move_to_trash	Move items to Trash
empty_trash	Empty Trash
get_selected_files	Get Finder selection
search_files	Search using Spotlight

Calendar (3 tools)

Tool	Description
list_calendars	List all calendars
list_calendar_events	List upcoming events
create_calendar_event	Create new event

Reminders (5 tools)

Tool	Description
list_reminder_lists	List reminder lists
list_reminders	List reminders
create_reminder	Create new reminder
complete_reminder	Mark reminder complete
get_overdue_reminders	Get overdue items

Scripts (4 tools)

Tool	Description
run_applescript	Execute AppleScript code
run_shell_command	Execute shell command (with safety checks)
open_url	Open URL in browser
open_file	Open file with app

Task Scheduler (3 tools)

Tool	Description
create_scheduled_task	Create launchd task
list_scheduled_tasks	List managed tasks
remove_scheduled_task	Remove a task

Complete Tool List (Alphabetical)

choose_from_list, clear_clipboard, complete_reminder, create_calendar_event,
create_folder, create_reminder, create_scheduled_task, empty_trash,
get_clipboard, get_frontmost_app, get_overdue_reminders, get_selected_files,
get_system_info, get_volume, get_wifi_network, hide_app, is_app_running,
is_dark_mode, launch_app, list_calendar_events, list_calendars,
list_reminder_lists, list_reminders, list_running_apps, list_scheduled_tasks,
move_to_trash, open_file, open_url, quit_app, remove_scheduled_task,
reveal_in_finder, run_applescript, run_shell_command, say_text, search_files,
send_alert, send_notification, set_clipboard, set_dark_mode, set_volume,
sleep_display, take_screenshot, toggle_dark_mode, toggle_mute, toggle_wifi

Example Usage

Via Claude/Cursor

"Set my system volume to 50%"
"What applications are currently running?"
"Send me a notification with title 'Reminder' and message 'Check email'"
"Create a calendar event for tomorrow at 2pm called 'Team Meeting'"
"What's on my clipboard?"

Via MCP Tool Calls

# Set volume
result = await callMCPTool('macos-automation__set_volume', {'level': 50})

# Send notification
result = await callMCPTool('macos-automation__send_notification', {
    'title': 'Hello',
    'message': 'World'
})

# List running apps
result = await callMCPTool('macos-automation__list_running_apps', {})

Security

Shell Command Safety

The run_shell_command tool includes safety checks that block dangerous commands. Only whitelisted commands are allowed:

• System info: sw_vers, uname, hostname, whoami, etc.
• File info: ls, pwd, stat, file, etc.
• Network info: networksetup, ifconfig, etc.
• macOS utilities: defaults, launchctl, open, etc.

Dangerous patterns like rm -rf /, sudo rm, fork bombs, etc. are blocked.

AppleScript Sandboxing

AppleScript execution respects macOS sandboxing and permission systems. Scripts cannot access protected resources without proper permissions.

Development

Running Tests

uv run pytest tests/ -v

Verification

# Verify server loads correctly
cd /Volumes/dev-4tb/AA-GitHub/MCP/mcp-applescript-automation
uv run python -c "from macos_automation_mcp import mcp; print(f'Server: {mcp.name}')"

# List all registered tools
uv run python -c "
from macos_automation_mcp.server import mcp
tools = list(mcp._tool_manager._tools.keys())
print(f'Registered {len(tools)} tools')
for t in sorted(tools): print(f'  - {t}')
"

# Test basic functionality
uv run python -c "
from macos_automation_mcp.domains import system
result = system.get_system_info()
print(f'macOS: {result.get(\"macos_version\")}')
print(f'Host: {result.get(\"hostname\")}')
"

Project Structure

mcp-applescript-automation/
├── macos_automation_mcp/
│   ├── __init__.py
│   ├── server.py              # FastMCP server with 45 tool definitions
│   ├── core/
│   │   ├── __init__.py
│   │   ├── applescript.py     # AppleScript execution engine (osascript)
│   │   ├── shell.py           # Safe shell command execution
│   │   └── scheduler.py       # launchd task integration
│   ├── domains/
│   │   ├── __init__.py
│   │   ├── system.py          # System controls (12 tools)
│   │   ├── applications.py    # Application control (6 tools)
│   │   ├── finder.py          # Finder operations (6 tools)
│   │   ├── calendar.py        # Calendar.app integration (3 tools)
│   │   ├── reminders.py       # Reminders.app integration (5 tools)
│   │   ├── notifications.py   # Notification Center (3 tools)
│   │   ├── clipboard.py       # Clipboard operations (3 tools)
│   │   └── scripts.py         # Script execution (4 tools)
│   └── models/
│       ├── __init__.py
│       └── schemas.py         # Pydantic models for type safety
├── tests/
│   ├── __init__.py
│   └── test_applescript.py    # Unit tests
├── main.py                    # Entry point
├── pyproject.toml             # Dependencies: mcp[cli], pydantic
├── uv.lock                    # Locked dependencies
└── README.md

Dependencies

• mcp[cli]>=1.0.0 - FastMCP framework with CLI support
• pydantic>=2.0.0 - Type-safe data validation

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Acknowledgments

• Built using FastMCP
• Inspired by applescript-mcp
• Uses the Model Context Protocol