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
click	Performs a mouse click (left, right, or middle button)
double_click	Performs a double-click
move_mouse	Moves the cursor without clicking
drag	Performs a drag operation from start to end coordinates

Keyboard Input

Tool	Description
type_text	Types text at the current cursor position
press_key	Presses a key by name (Enter, Tab, Escape, F1-F12, etc.)
key_combination	Presses a key combination (e.g., Cmd+C, Cmd+Shift+S)

Scroll and Navigation

Tool	Description
scroll	Scrolls in a specified direction (up, down, left, right)
scroll_to_element	Scrolls until a UI element becomes visible

Screenshots

Tool	Description
take_screenshot	Captures screen, display, window, or region as PNG/JPEG

Screenshot Features:

• Auto-resize: Screenshots are resized to max 1600px (configurable) for API compatibility
• Auto-compress: File size limited to 1.8MB using JPEG compression when needed
• Full resolution: Use rawFile: true for file output at full resolution
• Disable processing: Set maxDimension: 0 and maxFileSize: 0 to disable all processing

UI Element Interaction

Tool	Description
get_ui_elements	Retrieves the UI element tree for an application
click_ui_element	Clicks a UI element by path
get_ui_element_value	Gets the value of a UI element
set_ui_element_value	Sets the value of an editable UI element
focus_ui_element	Sets keyboard focus to a UI element

Menu Bar Operations

Tool	Description
list_menu_items	Gets the menu hierarchy for an application
click_menu_item	Clicks a menu item by path (e.g., "File > Save")
get_menu_item_state	Gets enabled/checked state of a menu item
list_status_bar_items	Lists visible status bar items
click_status_bar_item	Clicks a status bar item to open its menu
click_status_bar_menu_item	Clicks a menu item within a status bar menu
get_menu_bar_structure	Gets complete menu bar hierarchy for a process

macOS Permissions

This server requires specific macOS permissions to function. The first time you use certain tools, macOS will prompt you to grant access.

Required Permissions

1. Accessibility

Required for: Keyboard input, mouse control, UI element interaction, window management

Grant access:

1. Open System Settings > Privacy & Security > Accessibility
2. Click the + button and add your terminal app (Terminal, iTerm2, or Claude Code)
3. Toggle the switch to enable access
4. Restart your terminal after granting permission

Quick access:

open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"

2. Automation

Required for: Controlling other applications (Finder, Safari, etc.)

Grant access:

1. Open System Settings > Privacy & Security > Automation
2. Find your terminal app in the list
3. Enable checkboxes for target applications you want to control
4. If prompted during first use, click OK to allow

Quick access:

open "x-apple.systempreferences:com.apple.preference.security?Privacy_Automation"

3. Screen Recording

Required for: Screenshots

Grant access:

1. Open System Settings > Privacy & Security > Screen Recording
2. Click the + button and add your terminal app
3. Toggle the switch to enable access
4. Restart your terminal after granting permission

Quick access:

open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"

Troubleshooting Permissions

Issue	Solution
Permission added but not working	Restart your terminal app completely (Cmd+Q, then reopen)
App not appearing in permission list	Run the operation once to trigger the permission dialog
Permission still denied after granting	Remove the app from the list, restart, then re-add it
All permission issues persist	Restart macOS
"assistive access" error	Grant Accessibility permission specifically
"-1743" error code	Grant Automation permission for the target app
Screenshot returns black image	Grant Screen Recording permission and restart

Permission Checklist

Before using mac-mcp-server, verify these permissions are granted:

• [ ] Accessibility - Terminal/Claude Code added and enabled
• [ ] Automation - Target apps enabled under your terminal
• [ ] Screen Recording - Terminal/Claude Code added and enabled
• [ ] App restarted after granting permissions

Usage Examples

System Information

// Get system info
await get_system_info({})
// Returns: { macOSVersion: "15.0", hardwareModel: "MacBook Pro", ... }

// Get battery status
await get_battery_status({})
// Returns: { percentage: 85, isCharging: true, isDesktop: false }

Application Management

// List running applications
await list_running_apps({})
// Returns: [{ name: "Safari", bundleId: "com.apple.Safari", processId: 1234 }, ...]

// Launch an application
await launch_app({ name: 'Safari' })

// Quit an application
await quit_app({ name: 'Safari' })

Window Management

// List all windows
await list_windows({})

// Focus a specific window
await focus_window({ appName: 'Finder', windowIndex: 1 })

// Move a window
await move_window({ appName: 'Finder', x: 100, y: 100 })

// Resize a window
await resize_window({ appName: 'Finder', width: 800, height: 600 })

Keyboard and Mouse

// Type text
await type_text({ text: 'Hello, World!' })

// Press a key
await press_key({ key: 'enter' })

// Key combination (Cmd+C)
await key_combination({ modifiers: ['command'], key: 'c' })

// Click at coordinates
await click({ x: 500, y: 300 })

// Right-click
await click({ x: 500, y: 300, button: 'right' })

// Cmd+click
await click({ x: 500, y: 300, modifiers: ['command'] })

Screenshots

// Capture full screen (auto-resized and compressed for API)
await take_screenshot({})

// Capture to file (also auto-processed by default)
await take_screenshot({ filePath: '/tmp/screenshot.png' })

// Capture at full resolution (no processing)
await take_screenshot({ filePath: '/tmp/full.png', rawFile: true })

// Capture specific region
await take_screenshot({
  region: { x: 100, y: 100, width: 800, height: 600 },
})

// Custom compression settings
await take_screenshot({
  maxDimension: 1920, // Max 1920px
  maxFileSize: 1_000_000, // Max 1MB
  quality: 70, // JPEG quality 70
})

// Disable all processing for base64 output
await take_screenshot({ maxDimension: 0, maxFileSize: 0 })

UI Element Interaction

// Get UI element tree
await get_ui_elements({ appName: 'Safari', maxDepth: 3 })

// Click a button by path
await click_ui_element({
  appName: 'Safari',
  elementPath: 'window1/button1',
})

// Set text field value
await set_ui_element_value({
  appName: 'TextEdit',
  elementPath: 'window1/textfield1',
  value: 'New text',
})

Menu Operations

// List application menus
await list_menu_items({ appName: 'Finder' })

// Click a menu item
await click_menu_item({
  appName: 'Finder',
  menuPath: 'File > New Finder Window',
})

// Get menu item state
await get_menu_item_state({
  appName: 'Finder',
  menuPath: 'View > Show Path Bar',
})

Installation from Source

For development or customization:

git clone https://github.com/laststance/mac-mcp-server.git
cd mac-mcp-server
pnpm install
pnpm build

Then configure Claude Code to use the local build:

{
  "mcpServers": {
    "mac-mcp-server": {
      "command": "node",
      "args": ["/path/to/mac-mcp-server/dist/index.js"]
    }
  }
}

Development

Commands

Command	Description
pnpm build	Build for production
pnpm dev	Development mode (watch)
pnpm test	Run tests
pnpm typecheck	TypeScript type checking
pnpm lint	Lint code
pnpm lint:fix	Lint and auto-fix
pnpm format	Format code with Prettier

Project Structure

mac-mcp-server/
├── src/
│   ├── index.ts           # Entry point, MCP server setup
│   ├── lib/
│   │   ├── server.ts      # MCP server configuration
│   │   ├── executor.ts    # AppleScript execution
│   │   ├── permission.ts  # Permission checking and guidance
│   │   └── sanitizer.ts   # Input sanitization
│   └── tools/
│       ├── system.ts      # System information tools
│       ├── clipboard.ts   # Clipboard management
│       ├── notification.ts # Notification display
│       ├── audio.ts       # Audio control
│       ├── application.ts # Application lifecycle
│       ├── finder.ts      # Finder integration
│       ├── window.ts      # Window management
│       ├── mouse.ts       # Mouse control
│       ├── keyboard.ts    # Keyboard input
│       ├── scroll.ts      # Scroll operations
│       ├── screenshot.ts  # Screenshot capture
│       ├── ui-element.ts  # UI element interaction
│       └── menu.ts        # Menu bar operations
├── dist/                  # Compiled output
├── package.json
└── tsconfig.json

Security

This MCP server is designed with security in mind:

• AppleScript-only execution: All automation is performed through AppleScript and JXA. No arbitrary shell commands are executed.
• Input sanitization: All user inputs are sanitized before being included in AppleScript to prevent injection attacks.
• No data persistence: The server does not store any user data or credentials.
• Permission-gated access: All sensitive operations require explicit macOS permission grants.
• Scoped automation: Each tool has a specific, limited purpose rather than providing general system access.

Requirements

Requirement	Version
macOS	10.15 (Catalina) or later
Node.js	20.11.0 or later
pnpm	10.28.0 (for development)

License

MIT

Author

Laststance.io

Contributing

Contributions are welcome. Please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request