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

Audio Control

Clipboard and Notifications

Application Management

Finder Integration

Window Management

Mouse Control

Keyboard Input

Scroll and Navigation

Screenshots

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

Menu Bar Operations

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

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

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

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