项目简介

本项目 'mcp-vnc-macos-use' 是一个基于 Model Context Protocol (MCP) 构建的服务器，它利用 VNC 协议，使得 LLM 客户端能够远程控制 macOS 机器。该服务器无需在 macOS 端安装任何额外的应用程序，只需启用“屏幕共享”功能即可。借助此 MCP 服务器，用户可以使用任何 LLM（例如 Claude）来操作 macOS 系统，实现自动化任务、信息获取等。

主要功能点

远程屏幕截图: LLM 可以通过调用工具获取 macOS 机器的实时屏幕截图，用于视觉分析和任务规划。
键盘输入模拟: 支持 LLM 模拟键盘输入，包括文本输入、特殊按键（如回车、Tab、Esc）和组合键（如 Command+C, Ctrl+Alt+Delete），实现文本编辑、快捷操作等。
鼠标操作模拟: 支持 LLM 模拟鼠标移动和点击操作，包括单击、双击、右键单击、拖拽和滚动，实现图形界面交互。
坐标缩放: 提供坐标缩放工具，方便 LLM 在不同分辨率的屏幕上进行精确的鼠标操作。
集成 Anthropic API (Claude): 内置与 Anthropic API 的集成，允许 LLM 基于屏幕内容和用户指令规划并执行一系列屏幕操作，实现更高级的自动化任务。
Docker 部署: 提供 Docker 镜像，方便用户快速部署和跨平台使用。
仅支持macOS原生屏幕共享: 无需在目标macOS机器上安装任何第三方VNC服务器软件，直接使用系统自带的“屏幕共享”功能。
Apple 认证 (协议 30): 目前仅支持 Apple 认证协议 30，确保与 macOS 屏幕共享的兼容性和安全性。

注意限制:

目前仅支持 macOS 机器作为被控制端。
仅支持 Apple 认证协议 30，可能与其他VNC服务器不兼容。
鼠标和键盘输入功能尚在开发中，当前版本可能仅支持屏幕截图功能。

安装步骤

克隆仓库:

git clone https://github.com/baryhuang/mcp-vnc-macos-use.git
cd mcp-vnc-macos-use

构建 Docker 镜像 (推荐):
```
docker build -t mcp-vnc-macos-use .
```
或者，如果您需要支持多平台，可以使用 'docker buildx' (具体命令请参考仓库 README)。

服务器配置

对于 MCP 客户端 (例如 Claude Desktop)，您需要配置 MCP 服务器的启动命令。以下是使用 Docker 镜像的配置示例 (JSON 格式)：

{
  "mcpServers": {
    "vnc-macos-use": {  // 服务器名称，客户端内唯一标识即可
      "command": "docker", // 启动命令，这里使用 docker
      "args": [          // 命令参数
        "run",          // docker run 子命令
        "-i",           // 保持STDIN打开，即使没有连接
        "--rm",         // 容器退出后自动删除
        "buryhuang/mcp-vnc-macos-use:latest" // Docker 镜像名称
      ]
    }
  }
}

配置说明:

'"vnc-macos-use"': MCP 服务器的名称，可以自定义，在客户端配置中用于引用此服务器。
'"command": "docker"': 指定启动服务器的命令为 'docker'。
'"args"': 启动命令的参数列表。
- '"run"': 'docker run' 命令，用于运行容器。
- '"-i", "--rm"': Docker 运行参数，保持 STDIN 打开和容器退出后自动删除。
- '"buryhuang/mcp-vnc-macos-use:latest"': Docker 镜像名称，确保与您构建或拉取的镜像名称一致。

注意: 请确保您的系统已安装 Docker 并可以正常运行 Docker 命令。

基本使用方法

启动 MCP 服务器: 根据您的部署方式 (Docker 或本地运行)，启动 MCP 服务器。如果您使用 Docker，配置 Claude Desktop 后，当 Claude 需要使用该 MCP 服务器时，会自动启动 Docker 容器。
配置 MCP 客户端: 在您的 MCP 客户端 (例如 Claude Desktop) 中，添加上述服务器配置信息。
使用工具: LLM 客户端可以通过调用以下工具与 macOS 机器进行交互：
- 'vnc_macos_get_screen': 获取远程 macOS 机器的屏幕截图。需要提供 VNC 服务器的 'host', 'port', 'password' (和可选的 'username')。
- 'vnc_macos_send_keys': 模拟键盘输入。可以发送 'text' 文本、'special_key' 特殊按键或 'key_combination' 组合键。同样需要提供 VNC 连接信息。
- 'vnc_macos_send_mouse': 模拟鼠标操作。需要提供目标坐标 'x', 'y' 和操作 'action' (move, click, double_click, press, release, scroll_up, scroll_down)。坐标可以使用 'vnc_macos_scale_coordinates' 工具进行缩放。同样需要 VNC 连接信息。
- 'vnc_macos_scale_coordinates': 坐标缩放工具。根据参考屏幕尺寸 ('source_width', 'source_height') 和实际坐标 'x', 'y'，计算在 VNC 服务器实际屏幕上的缩放坐标。
- 'vnc_macos_plan_screen_actions': 高级工具，结合 Anthropic API 和屏幕截图，根据 'prompt' 规划屏幕操作。需要提供 Anthropic API 密钥 'anthropic_api_key' 和 VNC 连接信息。
查阅资源: 可以通过读取 'vnc://controls' 资源获取更详细的键盘和鼠标控制文档，了解支持的特殊按键、组合键和鼠标动作。

示例工具调用 (JSON 格式):

获取屏幕截图:

{
  "tool_call": {
    "name": "vnc_macos_get_screen",
    "arguments": {
      "host": "your_vnc_host",
      "port": 5900,
      "password": "your_vnc_password",
      "username": "your_vnc_username" // 可选
    }
  }
}

发送文本 "Hello":

{
  "tool_call": {
    "name": "vnc_macos_send_keys",
    "arguments": {
      "host": "your_vnc_host",
      "port": 5900,
      "password": "your_vnc_password",
      "text": "Hello"
    }
  }
}

请注意: 使用 VNC 远程控制涉及安全风险，请确保您只连接到您信任的 macOS 机器，并妥善保管 VNC 密码。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息