Mac MCP Server

mac mcp服务器

macOS AppleScript MCP（模型上下文协议）服务器，使Claude Code和其他AI助手能够通过AppleScript和JXA（JavaScript for Automation）自动化macOS。

概述

此MCP服务器为全面的macOS自动化提供了44个工具，使AI助手能够：

• 检索系统信息（硬件、电池、显示器）
• 管理应用程序（启动、退出、激活、列出正在运行的应用程序）
• 控制窗口（移动、调整大小、聚焦、最小化）
• 模拟键盘和鼠标输入
• 通过辅助功能API与UI元素交互
• 捕获屏幕截图（针对API兼容性进行了自动优化）
• 访问剪贴板和通知
• 控制音频设置
• 导航菜单和状态栏项目

服务器通过stdio进行通信，以实现无缝的克劳德代码集成，并使用AppleScript/JXA进行系统自动化。

快速开始

先决条件

• macOS 10.15（Catalina）或更高版本
• Node.js 20.11.0或更高版本

从npm安装

npm install -g mac-mcp-server

配置Claude代码

将以下内容添加到您的Claude Code MCP配置中(~/.claude.json 或克劳德桌面设置）：

{
  "mcpServers": {
    "mac-mcp-server": {
      "command": "npx",
      "args": ["-y", "mac-mcp-server"]
    }
  }
}

重新启动Claude Code以加载MCP服务器。

授予macOS权限

首次使用时，macOS会提示您授予所需的权限。请参阅 权限指南 详见下文。

工具参考

系统信息

音频控制

剪贴板和通知

应用管理

Finder集成

窗口管理

鼠标控制

键盘输入

滚动和导航

截图

屏幕截图功能：

• 自动调整大小：屏幕截图的大小调整为最大1600px（可配置），以实现API兼容性
• 自动压缩：需要时使用JPEG压缩将文件大小限制为1.8MB
• 全分辨率：使用 rawFile: true 用于以全分辨率输出文件
• 禁用处理：设置 maxDimension: 0 和 maxFileSize: 0 禁用所有处理

UI元素交互

菜单栏操作

macOS权限

此服务器需要特定的macOS权限才能运行。首次使用某些工具时，macOS会提示您授予访问权限。

必需的权限

1.无障碍

需要： 键盘输入、鼠标控制、UI元素交互、窗口管理

授予访问权限：

1. 打开 系统设置>隐私和安全>辅助功能
2. 点击 + 按钮并添加您的终端应用程序（终端、iTerm2或克劳德代码）
3. 切换开关以启用访问
4. 重新启动终端 授予许可后

快速访问：

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

2.自动化

需要： 控制其他应用程序（Finder、Safari等）

授予访问权限：

1. 打开 系统设置>隐私和安全>自动化
2. 在列表中查找您的终端应用程序
3. 为要控制的目标应用程序启用复选框
4. 如果首次使用时出现提示，请单击 好的 允许

快速访问：

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

3.屏幕录制

需要： 截图

授予访问权限：

1. 打开 系统设置>隐私和安全>屏幕录制
2. 点击 + 按钮并添加您的终端应用程序
3. 切换开关以启用访问
4. 重新启动终端 授予许可后

快速访问：

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

权限疑难解答

权限检查表

在使用mac mcp服务器之前，请验证是否授予了这些权限：

• \[ \] 无障碍 -终端/Claude代码已添加并启用
• \[ \] 自动化 -在您的终端下启用的目标应用程序
• \[ \] 屏幕录制 -终端/Claude代码已添加并启用
• \[ \] 应用程序已重新启动 授予权限后

使用示例

系统信息

// 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 }

应用管理

// 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' })

窗口管理

// 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 })

键盘和鼠标

// 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'] })

截图

// 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元素交互

// 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',
})

菜单操作

// 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',
})

从源安装

对于开发或定制：

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

然后配置Claude Code以使用本地构建：

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

发展

命令

项目结构

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

安全

此MCP服务器的设计考虑了安全性：

• 仅执行AppleScript：所有自动化都是通过AppleScript和JXA执行的。不会执行任意shell命令。
• 输入净化：所有用户输入在包含在AppleScript中之前都经过消毒，以防止注入攻击。
• 无数据持久性：服务器不存储任何用户数据或凭据。
• 权限门控访问：所有敏感操作都需要明确的macOS权限授予。
• 自动化范围：每个工具都有特定的、有限的用途，而不是提供一般的系统访问。

需求

许可证

麻省理工学院

作者

Laststance.io

贡献

欢迎捐款。请先打开一个问题，讨论您想更改什么。

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求