Provides tools to automate macOS system operations, including system control (volume, dark mode, WiFi, screenshots), application management, notifications, clipboard, Finder, Calendar, Reminders, script execution, and task scheduling via AppleScript.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@macOS Automation MCP Server list running applications"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: mac-mcp-server
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 macOS version, hostname, user, and uptime |
| Set system volume (0-100) |
| Get current volume level |
| Toggle audio mute |
| Toggle dark/light mode |
| Set dark mode explicitly |
| Check if dark mode is enabled |
| Put display to sleep |
| Speak text using TTS |
| Capture screenshot |
| Get current WiFi network |
| Enable/disable WiFi |
Tool | Description |
| List all running applications |
| Get active application info |
| Launch an application |
| Quit an application |
| Hide an application |
| Check if app is running |
Tool | Description |
| Send macOS notification |
| Show alert dialog |
| Show selection dialog |
Tool | Description |
| Get clipboard text |
| Copy text to clipboard |
| Clear clipboard |
Tool | Description |
| Reveal file in Finder |
| Create new folder |
| Move items to Trash |
| Empty Trash |
| Get Finder selection |
| Search using Spotlight |
Tool | Description |
| List all calendars |
| List upcoming events |
| Create new event |
Tool | Description |
| List reminder lists |
| List reminders |
| Create new reminder |
| Mark reminder complete |
| Get overdue items |
Tool | Description |
| Execute AppleScript code |
| Execute shell command (with safety checks) |
| Open URL in browser |
| Open file with app |
Tool | Description |
| Create launchd task |
| List managed tasks |
| 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.mdmcp[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
Show a list selection dialog.
Args: items: List of items to choose from title: Dialog title prompt: Optional prompt message multiple: Allow multiple selections
Inputs: items (required), title, prompt, multiple. Returns: result
Clear the clipboard contents.
Inputs: no named parameters. Returns: result
Mark a reminder as complete.
Args: title: Reminder title to complete list_name: Optional specific list to search in
Inputs: title (required), list_name. Returns: result
Create a new calendar event.
Args: title: Event title start_date: Start date/time (ISO format: YYYY-MM-DDTHH:MM:SS) end_date: End date/time (ISO format: YYYY-MM-DDTHH:MM:SS) calendar_name: Calendar to add event to (default: "Calendar") location: Optional event location notes: Optional event notes
Inputs: title (required), end_date (required), start_date (required), notes, +2 more. Returns: result
Create a new folder.
Args: path: Full path for the new folder
Inputs: path (required). Returns: result
Create a new reminder.
Args: title: Reminder title list_name: Reminder list to add to (default: "Reminders") due_date: Optional due date (ISO format: YYYY-MM-DDTHH:MM:SS) notes: Optional notes
Inputs: title (required), notes, due_date, list_name. Returns: result
Create a scheduled task using launchd.
Args: name: Unique name for the task command: Command to execute interval_seconds: Run every N seconds (min 60) hour: Hour to run (0-23) for calendar schedule minute: Minute to run (0-59) for calendar schedule run_at_load: Run immediately when loaded
Inputs: name (required), command (required), hour, minute, +2 more. Returns: result
Empty the Trash.
Inputs: no named parameters. Returns: result
Get the current clipboard contents as text.
Inputs: no named parameters. Returns: result
Get information about the currently active (frontmost) application.
Inputs: no named parameters. Returns: result
Get all overdue reminders.
Inputs: no named parameters. Returns: result
Get the currently selected files in Finder.
Inputs: no named parameters. Returns: result
Get macOS system information including hostname, version, user, and uptime.
Inputs: no named parameters. Returns: result
Get the current system volume level.
Inputs: no named parameters. Returns: result
Get the current WiFi network name.
Inputs: no named parameters. Returns: result
Hide an application's windows.
Args: app_name: Name of the application to hide
Inputs: app_name (required). Returns: result
Check if an application is currently running.
Args: app_name: Name of the application to check
Inputs: app_name (required). Returns: result
Check if dark mode is currently enabled.
Inputs: no named parameters. Returns: result
Launch an application.
Args: app_name: Name of the application (e.g., 'Safari', 'Finder', 'Terminal') new_instance: If True, opens a new instance of the app
Inputs: app_name (required), new_instance. Returns: result
List upcoming calendar events.
Args: days_ahead: Number of days to look ahead (default: 7) calendar_name: Optional specific calendar name
Inputs: days_ahead, calendar_name. Returns: result
List all available calendars.
Inputs: no named parameters. Returns: result
List all reminder lists.
Inputs: no named parameters. Returns: result
List reminders.
Args: list_name: Optional specific reminder list include_completed: Include completed reminders
Inputs: list_name, include_completed. Returns: result
List all currently running applications.
Inputs: no named parameters. Returns: result
List all MCP-managed scheduled tasks.
Inputs: no named parameters. Returns: result
Move files or folders to the Trash.
Args: paths: List of paths to move to trash
Inputs: paths (required). Returns: result
Open a file with the default or specified application.
Args: path: Path to the file app_name: Optional application name to open with
Inputs: path (required), app_name. Returns: result
Open a URL in the default browser.
Args: url: URL to open
Inputs: url (required). Returns: result
Quit an application.
Args: app_name: Name of the application to quit force: If True, force quits without saving
Inputs: app_name (required), force. Returns: result
Remove a scheduled task.
Args: name: Name of the task to remove
Inputs: name (required). Returns: result
Reveal a file or folder in Finder.
Args: path: Path to the file or folder
Inputs: path (required). Returns: result
Execute arbitrary AppleScript code.
Args: script: AppleScript code to execute timeout: Maximum execution time in seconds (default: 30)
Inputs: script (required), timeout. Returns: result
Execute a shell command (with safety checks).
Args: command: Shell command to execute timeout: Maximum execution time in seconds (default: 30) working_dir: Optional working directory
Inputs: command (required), timeout, working_dir. Returns: result
Speak text using text-to-speech.
Args: text: Text to speak voice: Optional voice name (e.g., 'Alex', 'Samantha', 'Victoria') rate: Optional speaking rate in words per minute
Inputs: text (required), rate, voice. Returns: result
Search for files using Spotlight.
Args: query: Search query location: Optional folder path to search in kind: Optional file type filter ('pdf', 'image', 'document', 'audio', 'video')
Inputs: query (required), kind, location. Returns: result
Show an alert dialog and wait for user response.
Args: title: Alert title message: Alert message buttons: List of button names (max 3) default_button: Name of the default button
Inputs: title (required), message (required), buttons, default_button. Returns: result
Send a macOS notification.
Args: title: Notification title message: Notification body text subtitle: Optional subtitle sound: Sound name ('default', 'Basso', 'Glass', 'Hero', 'Pop', etc.) or None for silent
Inputs: title (required), message (required), sound, subtitle. Returns: result
Copy text to the clipboard.
Args: text: Text to copy to clipboard
Inputs: text (required). Returns: result
Set dark mode to a specific state.
Args: enabled: True for dark mode, False for light mode
Inputs: enabled (required). Returns: result
Set the system volume level.
Args: level: Volume level from 0 (mute) to 100 (max)
Inputs: level (required). Returns: result
Put the display to sleep.
Inputs: no named parameters. Returns: result
Capture a screenshot.
Args: path: Optional save path (defaults to Desktop with timestamp) region: If True, allows selecting a region (interactive) to_clipboard: If True, saves to clipboard instead of file
Inputs: path, region, to_clipboard. Returns: result
Toggle between dark mode and light mode.
Inputs: no named parameters. Returns: result
Toggle system audio mute on/off.
Inputs: no named parameters. Returns: result
Enable or disable WiFi.
Args: enabled: True to enable WiFi, False to disable
Inputs: enabled (required). Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 45 tools
Most tools have clearly distinct purposes, and the descriptions help differentiate them. A few pairs like toggle_mute and set_volume, or set_dark_mode and toggle_dark_mode, have some functional overlap but remain distinguishable. Overall, an agent can reliably select the correct tool.
Tool names consistently follow a verb_noun pattern in snake_case, such as get_volume, set_volume, toggle_mute, and create_calendar_event. Prefixes like get_, set_, toggle_, list_, create_, and is_ are used predictably across domains. This makes the API easy to navigate.
With 45 tools, the server is excessively large for a single coherent MCP server. While the macOS automation scope is broad, many tools (e.g., calendar and reminder management) could be separated into focused servers. This volume overwhelms an agent's ability to efficiently select among them.
The server covers a wide range of macOS automation tasks including system controls, app management, file operations, calendar, reminders, and scripting. Minor gaps exist such as lack of file read/write operations or direct control of display brightness, but the core workflows are well-supported. Overall, the surface is fairly complete for its domain.
MCP connector that lets ChatGPT list, search, and run your Apple Shortcuts via a local Mac agent
Automate 1,000+ services from any MCP-compatible AI agent: build Applets, run actions and queries.
Build and run agents and automations across hundreds of apps using natural language.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
