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.
- macOS 26.1+ compatible
- All 45 tools registered and functional
- AppleScript execution engine tested
- Shell command safety validation active
- 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
- 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
- Script Execution: Run AppleScript and shell commands
- Task Scheduler: Create and manage launchd scheduled tasks
- macOS 10.15 or later
- Python 3.10 or later
- uv (recommended) or pip
cd /path/to/mcp-applescript-automation
uv synccd /path/to/mcp-applescript-automation
pip install -e .Add to your MCP configuration file:
{
"mcpServers": {
"macos-automation": {
"command": "uv",
"args": ["run", "--directory", "/path/to/mcp-applescript-automation", "python", "main.py"],
"env": {}
}
}
}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"
}This server requires certain macOS permissions to function:
-
Automation Permission (Required)
- System Preferences > Privacy & Security > Privacy > Automation
- Grant permission to your terminal app (Terminal, iTerm2, Cursor, etc.)
-
Accessibility Permission (For some UI automation)
- System Preferences > Privacy & Security > Privacy > Accessibility
- Required for advanced UI interactions
-
Calendar/Reminders Access (For calendar/reminder tools)
- System Preferences > Privacy & Security > Privacy > Calendars/Reminders
- Required for calendar and reminder management
| 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 |
| 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 |
| Tool | Description |
|---|---|
send_notification |
Send macOS notification |
send_alert |
Show alert dialog |
choose_from_list |
Show selection dialog |
| Tool | Description |
|---|---|
get_clipboard |
Get clipboard text |
set_clipboard |
Copy text to clipboard |
clear_clipboard |
Clear clipboard |
| 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 |
| Tool | Description |
|---|---|
list_calendars |
List all calendars |
list_calendar_events |
List upcoming events |
create_calendar_event |
Create new event |
| 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 |
| 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 |
| Tool | Description |
|---|---|
create_scheduled_task |
Create launchd task |
list_scheduled_tasks |
List managed tasks |
remove_scheduled_task |
Remove a task |
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
"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?"
# 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', {})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 execution respects macOS sandboxing and permission systems. Scripts cannot access protected resources without proper permissions.
uv run pytest tests/ -v# 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\")}')
"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
- mcp[cli]>=1.0.0 - FastMCP framework with CLI support
- pydantic>=2.0.0 - Type-safe data validation
MIT License
Contributions are welcome! Please feel free to submit issues and pull requests.
- Built using FastMCP
- Inspired by applescript-mcp
- Uses the Model Context Protocol