关键词

macOS远程控制VNC屏幕自动化LLM工具计算机使用

项目简介

VNC Remote macOS MCP服务器是一个基于 Model Context Protocol (MCP) 构建的应用后端，旨在让大型语言模型 (LLM) 能够远程控制任何开启了屏幕共享的macOS机器。该服务器无需在macOS端进行任何额外的安装配置，只需启用macOS的屏幕共享功能即可使用。它通过VNC协议与macOS机器通信，并以MCP标准协议与LLM客户端交互，为LLM提供了一组工具，使其能够获取macOS机器的屏幕截图，并模拟键盘和鼠标操作，从而实现远程自动化控制。

主要功能点

  • 远程屏幕截图: LLM可以通过工具调用获取远程macOS机器的实时屏幕截图，为视觉理解和任务规划提供依据。
  • 键盘模拟: LLM可以控制远程macOS机器的键盘输入，包括发送文本、特殊按键（如回车、Tab等）和组合键（如command+C）。
  • 鼠标模拟: LLM可以控制远程macOS机器的鼠标操作，包括移动、点击、双击、拖拽和滚动等动作。
  • 坐标缩放: 提供坐标缩放工具，方便LLM在不同分辨率下进行精确的鼠标操作。
  • 任务规划 (集成Anthropic API): 集成 Anthropic API，允许LLM基于屏幕截图和用户目标进行智能任务规划，自动执行屏幕操作。
  • Docker部署: 支持Docker容器化部署，方便快捷地在各种环境中使用。
  • 兼容Claude Desktop: 特别优化与 Claude Desktop 的集成，可以直接在 Claude 的配置中添加并使用该MCP服务器。
  • 无需macOS端安装: 零配置安装，只需开启macOS屏幕共享即可，简化部署流程。
  • Apple Authentication (协议30): 支持 macOS 屏幕共享默认使用的 Apple Authentication 协议，安全性高。

安装步骤

  1. 克隆仓库:

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

  2. 构建Docker镜像 (可选，推荐使用Docker部署):

    docker build -t mcp-vnc-macos-use .

    或者直接使用预构建的Docker镜像 'buryhuang/mcp-vnc-macos-use:latest'。

服务器配置 (Claude Desktop)

要将此MCP服务器与 Claude Desktop 客户端配合使用，您需要在 Claude Desktop 的配置文件中添加 'mcpServers' 配置。以下是使用Docker部署的服务器配置示例：

{
  "mcpServers": {
    "vnc-macos-use": {  // 服务器名称，可以自定义
      "command": "docker", // 启动服务器的命令，这里使用 docker
      "args": [ // 启动服务器命令的参数列表
        "run",  // docker run 命令
        "-i",   // 保持STDIN开放，即使没有连接
        "--rm", // 容器退出后自动删除
        "buryhuang/mcp-vnc-macos-use:latest" // 使用预构建的 Docker 镜像
      ]
    }
  }
}

配置参数说明:

  • '"vnc-macos-use"': 服务器名称，在Claude Desktop客户端中引用此服务器时使用。您可以自定义名称。
  • '"command": "docker"': 指定启动服务器的命令为 'docker'。
  • '"args"': 参数列表，用于配置 'docker run' 命令：
    • '"run"': docker 运行命令。
    • '"-i"' 和 '"--rm"': Docker 常用参数，保持STDIN开放和容器退出后自动删除。
    • '"buryhuang/mcp-vnc-macos-use:latest"': 指定使用的 Docker 镜像，这里使用了预构建的镜像。您也可以替换为您自己构建的镜像名称。

如果您不使用Docker部署，而是直接运行 'server.py' 文件，则配置应为：

{
  "mcpServers": {
    "vnc-macos-use": {
      "command": "python",
      "args": [
        "-m",
        "src.mcp_server_vnc_macos_use.server"
      ]
    }
  }
}

配置参数说明:

  • '"command": "python"': 指定启动服务器的命令为 'python'。
  • '"args"': 参数列表，用于配置 'python' 命令：
    • '"-m"': Python 以模块名运行程序的参数。
    • '"src.mcp_server_vnc_macos_use.server"': 指定要运行的 Python 模块路径。

请确保在运行服务器之前，您已经安装了Python环境和相关的依赖库 (如果选择本地运行)。

基本使用方法

配置完成后，在LLM客户端（如Claude Desktop）中，您可以使用以下工具来控制远程macOS机器。工具调用通常需要提供VNC服务器的连接信息，例如主机地址 ('host')、端口 ('port')、密码 ('password') 和用户名 ('username') (可选，建议提供)。

常用工具示例:

  • 'vnc_macos_get_screen': 获取屏幕截图

    {
  "tool_call_id": "get_screen_1",
  "tool_name": "vnc_macos_get_screen",
  "parameters": {
    "host": "your_vnc_host_or_ip",  // 替换为您的VNC服务器地址
    "port": 5900,                   // VNC服务器端口，默认为 5900
    "password": "your_vnc_password", // VNC服务器密码
    "username": "your_username"      // VNC服务器用户名 (可选)
  }
}

  • 'vnc_macos_send_keys': 发送键盘输入

    {
  "tool_call_id": "send_keys_1",
  "tool_name": "vnc_macos_send_keys",
  "parameters": {
    "host": "your_vnc_host_or_ip",
    "port": 5900,
    "password": "your_vnc_password",
    "text": "Hello, macOS!" // 要发送的文本
  }
}

  • 'vnc_macos_send_mouse': 发送鼠标操作

    {
  "tool_call_id": "send_mouse_1",
  "tool_name": "vnc_macos_send_mouse",
  "parameters": {
    "host": "your_vnc_host_or_ip",
    "port": 5900,
    "password": "your_vnc_password",
    "x": 500,                      // 鼠标 X 坐标 (需要先使用 vnc_macos_scale_coordinates 工具获取缩放后的坐标)
    "y": 300,                      // 鼠标 Y 坐标
    "action": "click"              // 鼠标动作，例如 "move", "click", "double_click", "scroll_down" 等
  }
}

  • 'vnc_macos_scale_coordinates': 缩放坐标

    {
  "tool_call_id": "scale_coords_1",
  "tool_name": "vnc_macos_scale_coordinates",
  "parameters": {
    "host": "your_vnc_host_or_ip",
    "port": 5900,
    "password": "your_vnc_password",
    "source_width": 1440,          // 参考屏幕宽度
    "source_height": 900,         // 参考屏幕高度
    "x": 100,                      // 参考屏幕上的 X 坐标
    "y": 100                       // 参考屏幕上的 Y 坐标
  }
}

  • 'vnc_macos_plan_screen_actions': 智能规划屏幕操作 (需要 Anthropic API Key)

    {
  "tool_call_id": "plan_actions_1",
  "tool_name": "vnc_macos_plan_screen_actions",
  "parameters": {
    "prompt": "打开 Safari 浏览器并访问 google.com", // 任务目标
    "anthropic_api_key": "YOUR_ANTHROPIC_API_KEY",  // 您的 Anthropic API Key
    "host": "your_vnc_host_or_ip",
    "port": 5900,
    "password": "your_vnc_password"
  }
}

请根据您的实际需求选择合适的工具，并参考工具的 'inputSchema' 填写正确的参数。 详细的键盘和鼠标控制文档可以查阅 'vnc://controls' 资源 (例如在 Claude 中可以提问 "read vnc://controls")。

安全性提示: 请确保您的VNC服务器密码安全，并仅在信任的网络环境中使用此MCP服务器。

信息

分类

桌面与硬件

访问项目