mouse-mcp - 让 AI 代理驱动真实 USB HID 鼠标的 MCP 服务器
mouse-mcp 是 SonicloudTech 维护的 MCP 服务器,据项目自述,它让 AI 代理通过兼容的 uMouse 硬件完成鼠标移动、点击、滚动与拖拽,并支持可插拔语音识别提供商的语音听写。项目采用 MIT 许可,要求 Windows x64 与单独安装的 Node.js 22 x64,普通 USB 鼠标不足以使用。
mouse-mcp 是由 SonicloudTech 维护的一个 Model Context Protocol(MCP)服务器,目标是把「真实的硬件鼠标」交给 AI 代理使用。据项目自述,它面向 Windows 平台,通过兼容的 uMouse USB HID 设备执行鼠标移动、点击、滚动和拖拽,同时提供语音听写能力,语音识别后端可以按需替换。它适合希望让代理在真实桌面环境里操作图形界面、而不是只在浏览器或 API 层活动的开发者与自动化团队。需要提前说明的是:项目自述明确要求配合兼容的 uMouse 硬件与固件、Windows x64 系统,以及单独安装的 Node.js 运行时(建议 Node.js 22 x64),一根普通的 USB 鼠标并不够用。
维护者与状态
仓库位于 SonicloudTech 组织下,许可证为 MIT。仓库创建于 2026-10-20,最后一次提交在 2026-10-31,最新正式发布为 v0.1.1(2026-10-23)。截至 2026-11-16,仓库星标数为 428。项目另有一个官网入口,见下文「使用入口」。
从时间线看,这是一个非常年轻的项目:创建到最新提交只有十余天,版本号仍停留在 0.1.x。项目自述也坦承发布包与源码是两条不同的安装路径——v0.1.0 的安装器注册的是旧的 stdio 入口 mcp/dist/index.js,而 README 中描述的 shared-v2 工具、原生宿主与验收实验室属于源码实现;ZIP 包并不是完整的 shared-v2 打包产物,也不包含原生宿主和验收实验室。项目自述还提到,目前尚未提供完整的公开 shared-v2 打包流程。评估时应当把「发布包能力」和「源码能力」分开看。
主要能力
以下能力均据项目自述整理,其中 shared-v2 部分对应源码实现,未必等同于发布包中的行为。
- 硬件鼠标动作:
umouse_mouse_action支持在桌面物理像素坐标下移动、点击、滚动与拖拽,可处理多显示器与负坐标,并提供precision: standard | high两档精度选项。 - 任务独占:
umouse_control以 begin → actions → end 的方式组织任务,同一时间只允许一个任务驱动鼠标与键盘,失效连接会被自动清理。 - 只读传感器:
umouse_input_status返回光标位置、实时按键状态与前台窗口身份,项目说明其只读、不拦截输入。 - 语音听写:麦克风采集 → VAD 分段 → 可插拔 ASR 提供商 → 预览与最终转写,作为独立通道运行,不会抢占鼠标控制。
- 共享守护进程:每台机器一个实例(端口 47192),在 ZCode、Codex、Claude 等宿主之间共享,空闲时回收。
- 自适应定位:项目自述内置 11 段弹道增益曲线,首次使用设备时从本地指针设置只读播种,在线逐帧学习并限制在 [0.125, 10] 区间,空闲 60 秒后衰减回种子值,换机器或换设备时无需手动调参。
语音识别方面,项目把 ASR 定义成一个很小的接口契约:实现 begin / writePcm / finishInput / cancel 并发出 preview / segmentFinal / warning / terminal 事件即可成为有效提供商。项目自述列出的提供商包括 sinicloud(默认,纯 TypeScript 流式识别)、windows-speech(Windows 内置、离线)、whisper-cpp(自托管、离线 CPU 转写)、http(自定义转写端点)以及 disabled。凭据只通过配置传入,按会话热读取,可通过 JSON 文件或环境变量覆盖,项目称其不会被硬编码、打印或写入日志。
使用入口
仓库地址:SonicloudTech/mouse-mcp;项目官网:sinicloud.com。
据项目说明,使用前需安装 Node.js 22 x64 并确认 node --version 可用,连接兼容的 uMouse USB 接收器或设备并开机。发布包有两种形态:MCPB 包(v0.1.1,适用于支持 MCPB Node 扩展的客户端)与 Windows x64 ZIP 包(v0.1.0)。ZIP 包已包含生产依赖、原生 SDK DLL、语音预览界面与 VC 运行库,无需 npm install 或编译,但 Node.js 本身不随包提供。
ZIP 路径下,解压后双击 install-agents.cmd 可在用户范围注册 ZCode,或从解压目录执行单条命令为指定客户端安装,例如 node mcp/scripts/install-agents.mjs claude 或 node mcp/scripts/install-agents.mjs cursor。安装器会在客户端配置中新增或更新 umouse 条目。对于接受 mcpServers JSON 的客户端,也可手动添加:
{
"mcpServers": {
"umouse": {
"command": "node",
"args": ["C:\\path\\to\\umouse-mcp-os-win-x64\\mcp\\dist\\index.js"]
}
}
}
项目建议安装后先让代理调用 umouse_status、umouse_get_capabilities 与 umouse_list_devices 检查 SDK 健康度、设备列表与能力上报;项目特别提醒,返回的 sdkVersion 只说明 SDK 可访问,并不证明硬件控制真的生效,应以实际可见的鼠标动作结果为准。源码开发路径为 npm ci、npm run build、npm test,但项目说明这些命令不会产出完整的 shared-v2 原生包。
许可与限制
仓库许可证为 MIT。需要注意,项目自述指出 MIT 许可覆盖的是服务器代码,原生 SDK 二进制文件另有条款,使用前应查阅仓库内的 License 说明。
已知限制与适用边界(据项目自述):
- 必须使用兼容的 uMouse 硬件与固件,普通 USB 鼠标无法替代;仅支持 Windows x64。
- Node.js 需单独安装,发布包不捆绑运行时。
- v0.1.1 的 MCPB 包不包含任何云端凭据,语音识别仅接受
disabled(默认)或windows-speech;v0.1.0 的 ZIP 包附带一份试用凭据,生产环境应替换为自己的密钥。 - 手动配置
mcpServers不会执行安装器的 ASR 初始化,需要语音听写时须另行配置提供商。 - 发布包与源码实现存在差异,shared-v2 的完整公开打包流程尚未提供。
综上,mouse-mcp 的定位相当明确:它不是一个通用的桌面自动化库,而是围绕特定硬件构建的 MCP 接入层。在硬件到位、系统匹配的前提下,它提供了一条从模型到真实输入管线的完整链路;反之,缺少兼容设备时它无法发挥作用。