MCPControl

MCPControl

适用于 Model Context Protocol 的 Windows 控制服务，可通过编程方式控制系统操作，包括鼠标、键盘、窗口管理和屏幕捕获功能。

注意：此项目目前仅支持 Windows。

🔥 为什么选择 MCPControl？

MCPControl 在 AI 模型与桌面之间架起桥梁，让你能够安全地通过编程方式控制：

• 🖱️ 鼠标移动和点击
• ⌨️ 键盘输入和快捷键
• 🪟 窗口管理
• 📸 屏幕捕获和分析
• 📋 剪贴板操作

🔌 快速开始

前置条件

1. 安装构建工具（包括 VC++ 工作负载）

   # Run as Administrator - may take a few minutes to complete
   winget install Microsoft.VisualStudio.2022.BuildTools --override "--wait --passive --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
   

2. 安装 Python（如果尚未安装）

   # Install Python (required for node-gyp)
   winget install Python.Python.3.12
   

3. 安装 Node.js

   # Install latest LTS version
   winget install OpenJS.NodeJS
   

安装

1. 安装 MCPControl 软件包

   npm install -g mcp-control
   

配置

为了获得最佳点击精度，建议在分辨率为 1280x720 的虚拟机中使用 MCPControl。

配置 Claude 客户端，通过 SSE 传输连接到 MCPControl：

选项 1：直接 SSE 连接

用于连接在虚拟机或远程计算机上运行的 MCPControl 服务：

{
  "mcpServers": {
    "MCPControl": {
      "transport": "sse",
      "url": "http://192.168.1.100:3232/mcp"
    }
  }
}

将 192.168.1.100:3232 替换为你的服务 IP 地址和端口。

选项 2：通过 SSE 本地启动

若要在本地通过 SSE 传输启动 MCPControl：

{
  "mcpServers": {
    "MCPControl": {
      "command": "mcp-control",
      "args": ["--sse"]
    }
  }
}

启动服务

首先，在虚拟机或本地计算机上启动 MCPControl 服务：

mcp-control --sse

服务将显示：

• 可用的网络接口及其 IP 地址
• 端口号（默认值：3232）
• 连接状态消息

虚拟机设置示例

1. 以 1280x720 分辨率启动 Windows 虚拟机
2. 在虚拟机上安装 MCPControl：

   npm install -g mcp-control
   

3. 通过 SSE 传输运行服务：

   mcp-control --sse
   

4. 记下虚拟机的 IP 地址（例如，192.168.1.100）
5. 使用 SSE URL 配置 Claude：

   {
     "mcpServers": {
       "MCPControl": {
         "transport": "sse",
         "url": "http://192.168.1.100:3232/mcp"
       }
     }
   }
   

6. 重启 Claude，MCPControl 就会出现在 MCP 菜单中！

🔧 CLI 选项

MCPControl 支持多个命令行标志，可用于高级配置：

# Run with SSE transport on default port (3232)
mcp-control --sse

# Run with SSE on custom port
mcp-control --sse --port 3000

# Run with HTTPS/TLS (required for production deployments)
mcp-control --sse --https --cert /path/to/cert.pem --key /path/to/key.pem

# Run with HTTPS on custom port
mcp-control --sse --https --port 8443 --cert /path/to/cert.pem --key /path/to/key.pem

命令行参数

• --sse - 启用 SSE（服务器发送事件）传输，以便通过网络访问
• --port [number] - 指定自定义端口（默认值：3232）
• --https - 启用 HTTPS/TLS（根据 MCP 规范，远程部署时必须启用）
• --cert [path] - TLS 证书文件路径（使用 --https 时必需）
• --key [path] - TLS 私钥文件路径（使用 --https 时必需）

安全说明

根据 MCP 规范，在生产环境中，所有基于 HTTP 的传输都必须使用 HTTPS。将 MCPControl 部署为远程访问服务时，务必使用 --https 标志和有效的 TLS 证书。

🚀 常见用例

辅助自动化

• 应用测试：将重复的 UI 测试交给 Claude，让 AI 浏览应用并报告问题
• 工作流自动化：让 Claude 代你操作应用、处理重复性任务，而你可以专注于创意工作
• 填写表单：在你的监督下，让 Claude 处理数据录入任务

AI 实验

• AI 游戏：观察 Claude 通过视觉反馈学习玩简单游戏
• 视觉推理：测试 Claude 浏览可视化界面和解决视觉谜题的能力
• 人机协作：探索全新的交互方式，让 Claude 能够查看你的屏幕并帮助处理复杂任务

开发和测试

• 跨应用集成：连接通常无法相互通信的应用
• UI 测试框架：创建具备视觉验证功能的稳健测试场景
• 演示创建：自动创建产品演示

⚠️ 重要免责声明

此软件尚处于实验阶段，且可能存在危险

使用此软件即表示你承认并接受：

• 通过此工具让 AI 模型直接控制你的计算机本身就有风险
• 此软件可以控制你的鼠标、键盘及其他系统功能，可能会造成意外后果
• 使用此软件的所有风险均由你自行承担
• 本项目的创建者和贡献者对使用此软件可能造成的任何损害、数据丢失或其他后果概不负责
• 此工具仅应在已采取适当安全措施的受控环境中使用

风险自负

🌟 功能

🪟 窗口管理 列出所有窗口 获取活动窗口信息 聚焦、调整大小和重新定位	🖱️ 鼠标控制 精准移动 点击和拖动操作 滚动和位置跟踪
⌨️ 键盘控制 文本输入和组合键 按键按下/释放控制 按住按键功能	📸 屏幕操作 高质量屏幕截图 检测屏幕尺寸 捕获活动窗口

🔧 自动化提供程序

MCPControl 支持多种自动化提供程序，以适应不同的使用场景：

• keysender（默认）- 可靠性高的原生 Windows 自动化
• powershell - 基于 Windows PowerShell 的自动化，适用于简单操作
• autohotkey - 使用 AutoHotkey v2 脚本满足高级自动化需求

提供程序配置

你可以使用环境变量配置自动化提供程序：

# Use a specific provider for all operations
export AUTOMATION_PROVIDER=autohotkey

# Configure AutoHotkey executable path (if not in PATH)
export AUTOHOTKEY_PATH="C:\Program Files\AutoHotkey\v2\AutoHotkey.exe"

也可以使用模块化配置来指定操作：

# Mix and match providers for different operations
export AUTOMATION_KEYBOARD_PROVIDER=autohotkey
export AUTOMATION_MOUSE_PROVIDER=keysender
export AUTOMATION_SCREEN_PROVIDER=keysender  
export AUTOMATION_CLIPBOARD_PROVIDER=powershell

请参阅特定提供程序的文档：

• AutoHotkey 提供程序

🛠️ 开发环境设置

如果你有兴趣参与贡献或从源代码构建，请参阅 CONTRIBUTING.md 获取详细说明。

开发要求

要为开发目的构建此项目，你需要：

1. Windows 操作系统（keysender 依赖项所必需）
2. Node.js 18 或更高版本（使用官方 Windows 安装程序安装，该安装程序包含构建工具）
3. npm 包管理器
4. 原生构建工具：
   • node-gyp：npm install -g node-gyp
   • cmake-js：npm install -g cmake-js

keysender 依赖项依赖于 Windows 专用的原生模块，这些模块需要上述构建工具。

📋 项目结构

• /src
  • /handlers - 请求处理程序和工具管理
  • /tools - 核心功能实现
  • /types - TypeScript 类型定义
  • index.ts - 应用程序主入口

🔖 仓库分支

• main - 包含最新功能和更改的主开发分支
• release - 稳定发布分支，与最新稳定标签保持一致（当前为 v0.2.0）

版本安装

你可以使用 npm 安装特定版本的 MCPControl：

# Install the latest stable release (from release branch)
npm install mcp-control

# Install a specific version
npm install [email protected]

📚 依赖项

• @modelcontextprotocol/sdk - 用于实现协议的 MCP SDK
• keysender - 仅适用于 Windows 的 UI 自动化库
• clipboardy - 剪贴板处理
• sharp - 图像处理
• uuid - UUID 生成

🚧 已知限制

• 目前不支持最小化/还原窗口操作
• 多屏幕功能可能无法按预期运行，具体取决于设置
• get_screenshot 工具无法与 VS Code 扩展 Cline 配合使用。请参阅 GitHub issue #1865
• 某些操作可能需要提升权限，具体取决于目标应用程序
• 仅支持 Windows
• MCPControl 在 1280x720 分辨率、单屏幕环境下效果最佳。点击准确度针对该分辨率进行了优化。我们正在修复偏移/缩放问题，并寻找测试人员或协助创建测试工具

👥 参与贡献

请参阅 CONTRIBUTING.md

⚖️ 许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。

📖 参考资料

• Model Context Protocol 文档