README.md
mac-mcp-server
A macOS AppleScript MCP (Model Context Protocol) server that enables Claude Code and other AI assistants to automate macOS through AppleScript and JXA (JavaScript for Automation).
Overview
This MCP server provides 44 tools for comprehensive macOS automation, allowing AI assistants to:
- Retrieve system information (hardware, battery, displays)
- Manage applications (launch, quit, activate, list running apps)
- Control windows (move, resize, focus, minimize)
- Simulate keyboard and mouse input
- Interact with UI elements via Accessibility APIs
- Capture screenshots (auto-optimized for API compatibility)
- Access clipboard and notifications
- Control audio settings
- Navigate menus and status bar items
The server communicates over stdio for seamless Claude Code integration and uses AppleScript/JXA for system automation.
Quick Start
Prerequisites
- macOS 10.15 (Catalina) or later
- Node.js 20.11.0 or later
Install from npm
npm install -g mac-mcp-server
Configure Claude Code
Add the following to your Claude Code MCP configuration (~/.claude.json or Claude Desktop settings):
{
"mcpServers": {
"mac-mcp-server": {
"command": "npx",
"args": ["-y", "mac-mcp-server"]
}
}
}
Restart Claude Code to load the MCP server.
Grant macOS Permissions
On first use, macOS will prompt you to grant required permissions. See the Permissions Guide below for details.
Tool Reference
System Information
| Tool | Description |
|---|---|
get_system_info |
Retrieves macOS version, hardware model, processor, and memory |
get_battery_status |
Gets battery percentage and charging status (MacBooks) |
get_display_info |
Lists connected displays with resolution information |
Audio Control
| Tool | Description |
|---|---|
get_volume |
Gets current system volume (0-100) |
set_volume |
Sets system volume to specified percentage |
get_mute_status |
Checks if system audio is muted |
set_mute |
Mutes or unmutes system audio |
Clipboard and Notifications
| Tool | Description |
|---|---|
get_clipboard |
Reads current clipboard content (text, image, or files) |
set_clipboard |
Sets clipboard to specified text |
send_notification |
Displays a macOS notification with optional subtitle and sound |
Application Management
| Tool | Description |
|---|---|
list_running_apps |
Lists all running GUI applications with bundle IDs and PIDs |
launch_app |
Launches an application by name |
quit_app |
Gracefully quits an application |
activate_app |
Brings an application to the foreground |
Finder Integration
| Tool | Description |
|---|---|
reveal_in_finder |
Opens Finder and selects the specified file or folder |
get_selected_files |
Gets paths of currently selected files in Finder |
get_finder_window_path |
Gets the path of the frontmost Finder window |
Window Management
| Tool | Description |
|---|---|
list_windows |
Lists all visible windows with position and size |
focus_window |
Brings a specific window to the front |
move_window |
Moves a window to specified coordinates |
resize_window |
Resizes a window to specified dimensions |
minimize_window |
Minimizes a window to the Dock |
Mouse Control
| Tool | Description |
|---|
Tools 22
get_system_infoRetrieves macOS version, hardware model, processor, and memoryget_battery_statusGets battery percentage and charging status (MacBooks)get_display_infoLists connected displays with resolution informationget_volumeGets current system volume (0-100)set_volumeSets system volume to specified percentageget_mute_statusChecks if system audio is mutedset_muteMutes or unmutes system audioget_clipboardReads current clipboard content (text, image, or files)set_clipboardSets clipboard to specified textsend_notificationDisplays a macOS notification with optional subtitle and soundlist_running_appsLists all running GUI applications with bundle IDs and PIDslaunch_appLaunches an application by namequit_appGracefully quits an applicationactivate_appBrings an application to the foregroundreveal_in_finderOpens Finder and selects the specified file or folderget_selected_filesGets paths of currently selected files in Finderget_finder_window_pathGets the path of the frontmost Finder windowlist_windowsLists all visible windows with position and sizefocus_windowBrings a specific window to the frontmove_windowMoves a window to specified coordinatesresize_windowResizes a window to specified dimensionsminimize_windowMinimizes a window to the DockTry it
→List all my currently running applications and quit the ones that are not in focus.
→Move my current browser window to the left half of the screen and resize it to 1280x800.
→Check my battery status and send me a notification if it is below 20%.
→Find the path of the folder currently open in the frontmost Finder window.
→Set the system volume to 50% and mute the audio.