Swift MCP GUI Server

Swift MCP GUI Server

一个模型上下文协议（MCP）服务，可通过 SwiftAutoGUI 控制 macOS。此服务通过 MCP 客户端提供以编程方式控制鼠标和键盘的工具。

要求

• macOS 27.0 或更高版本（SwiftAutoGUI 1.0.0 的要求）
• Swift 6.2 或更高版本
• Xcode 27.0 或更高版本

安装

Homebrew（推荐）

通过 NakaokaRei/tap 安装：

brew install NakaokaRei/tap/swift-mcp-gui

然后将 MCP 客户端指向已安装的二进制文件：

{
  "mcpServers": {
    "swift-mcp-gui": {
      "command": "/opt/homebrew/bin/swift-mcp-gui"
    }
  }
}

在 Intel Mac 上，路径为 /usr/local/bin/swift-mcp-gui。之后如需升级，请运行 brew upgrade swift-mcp-gui。

从源代码安装

1. 克隆此仓库：

git clone https://github.com/NakaokaRei/swift-mcp-gui.git
cd swift-mcp-gui

2. 安装

swift package experimental-install

3. 将命令添加到 MCP 客户端。

{
  "mcpServers" : {
    "swift-mcp-gui" : {
      "command" : "/Users/USERNAME/.swiftpm/bin/swift-mcp-gui"
    }
  }
}

可用工具

此服务提供以下用于控制 macOS 的工具：

1. 鼠标移动

• 工具名称：moveMouse
• 输入：
  • x：数字（x 坐标）——接受整数、浮点数或字符串表示形式
  • y：数字（y 坐标）——接受整数、浮点数或字符串表示形式
• 将鼠标光标移动到指定坐标

2. 鼠标点击

• 工具名称：mouseClick
• 输入：
  • button：字符串（"left" 或 "right"）
• 在当前光标位置执行鼠标点击

3. 键盘输入

• 工具名称：sendKeys
• 输入：
  • keys：字符串数组（按键名称）
• 发送键盘快捷键或组合键
• 按键示例："command"、"control"、"option"、"shift"、"return"、"space"、"a"、"1" 等

4. 滚动

• 工具名称：scroll
• 输入：
  • direction：字符串（"up"、"down"、"left"、"right"）
  • clicks：数字（滚动次数）
• 按指定方向滚动

5. 屏幕尺寸

• 工具名称：getScreenSize
• 返回主屏幕的尺寸（宽度和高度）

6. 像素颜色

• 工具名称：getPixelColor
• 输入：
  • x：数字（x 坐标）——接受整数、浮点数或字符串表示形式
  • y：数字（y 坐标）——接受整数、浮点数或字符串表示形式
• 返回指定坐标处像素的 RGBA 颜色值（0-255）

7. 捕获屏幕

• 工具名称：captureScreen
• 输入：
  • quality：数字（可选，0.0-1.0，默认值：0.5）——JPEG 压缩质量
  • scale：数字（可选，0.1-1.0，默认值：0.25）——图像尺寸缩放比例
  • output：字符串（可选，"path" 或 "image"，默认值："path"）——输出格式
• output: "path"（默认值）：保存到临时文件，并返回文件路径和尺寸。可减少 Token 消耗。
• output: "image"：返回内嵌图像内容，供 AI 视觉使用（例如 Claude）

8. 捕获区域

• 工具名称：captureRegion
• 输入：
  • x：数字（区域的 x 坐标）
  • y：数字（区域的 y 坐标）
  • width：数字（区域宽度）
  • height：数字（区域高度）
  • quality：数字（可选，0.0-1.0，默认值：0.5）——JPEG 压缩质量
  • scale：数字（可选，0.1-1.0，默认值：0.25）——图像尺寸缩放比例
  • output：字符串（可选，"path" 或 "image"，默认值："path"）——输出格式
• output: "path"（默认值）：保存到临时文件，并返回文件路径和尺寸。可减少 Token 消耗。
• output: "image"：返回内嵌图像内容，供 AI 视觉使用（例如 Claude）

9. 保存截图

• 工具名称：saveScreenshot
• 输入：
  • filename：字符串（保存截图的路径）
  • x：数字（可选，区域的 x 坐标）
  • y：数字（可选，区域的 y 坐标）
  • width：数字（可选，区域的宽度）
  • height：数字（可选，区域的高度）
  • quality：数字（可选，0.0-1.0，默认值：0.1）— JPEG 压缩质量
  • scale：数字（可选，0.1-1.0，默认值：0.25）— 图像尺寸的缩放比例
• 捕获整个屏幕或某个区域，并将其保存到文件
• 文件格式由文件名扩展名（.jpg、.jpeg、.png）决定
• 质量参数仅影响 JPEG 文件

10. 执行 AppleScript

• 工具名称：executeAppleScript
• 输入：
  • script：字符串（要执行的 AppleScript 代码）
• 直接执行 AppleScript 代码并返回结果
• 如果脚本返回值，则返回 "AppleScript Result: "
• 如果脚本执行完成但未返回值，则返回 "AppleScript executed successfully (no result returned)"

11. 执行 AppleScript 文件

• 工具名称：executeAppleScriptFile
• 输入：
  • path：字符串（AppleScript 文件的路径）
• 执行文件中的 AppleScript 并返回结果
• 如果脚本返回值，则返回 "AppleScript Result: "
• 如果脚本执行完成但未返回值，则返回 "AppleScript file executed successfully (no result returned): "

安全注意事项

此服务需要在“系统设置”中获得完整的辅助功能权限，才能控制鼠标和键盘。运行时请务必谨慎，并且仅连接可信的 MCP 客户端。

许可证

MIT 许可证