Magic Skill · Magic Mouse

Give Cursor Agent hands on your desktop — a Cursor-style desktop pet that operates your whole computer.

English · 中文 · Download · Docs · Developer Guide

---

📥 Download / 下载

Windows 10 / 11 only — Download the installer below, run it, restart Cursor once. Ready to use.

仅支持 Windows 10 / 11 — 直接下载下方安装包，安装后重启一次 Cursor 即可使用。

v0.1.0 Installers / 安装包

App	Size	Download
Magic Mouse ⭐ 主程序（桌宠 + Hub）	4.39 MB	⬇ Magic Mouse_0.1.0_x64-setup.exe
Magic Skill Launcher 可选控制台	2.09 MB	⬇ Magic Skill 控制台_0.1.0_x64-setup.exe

Installers are stored in the releases/ folder of this repo.
安装包位于本仓库 releases/ 目录，点击上方链接即可下载。

After install / 安装后：

1. Launch Magic Mouse from Start Menu → Magic Mouse
2. On first run it auto-installs the Cursor Skill, writes mcp.json, and pairs locally
3. Restart Cursor once
4. In Cursor chat, try: 用 Magic Mouse 查一下状态 — reply should say the pet is online

Manual build from source / 从源码构建

git clone https://github.com/WangYuecheng1106/Magic-Mouse.git
cd Magic-Mouse
npm run setup
npm run build:mouse        # → apps/magic-mouse/src-tauri/target/release/bundle/nsis/
npm run build:launcher     # optional; use: npx tauri build --bundles nsis
npm run shortcut           # desktop shortcut (Windows)

---

English

What is Magic Skill?

Magic Skill is a bridge between Cursor Agent and your real desktop. It combines:

Component	Role	Stack
Magic Mouse	A Cursor-style desktop pet that roams your screen, shows status, and physically moves mouse & keyboard	Tauri 2 · Rust · Svelte
Magic Skill (MCP)	Cursor Skill + MCP server — exposes 17+ mm_* tools to the Agent	Node 20+ · TypeScript · MCP SDK

You in Cursor  →  Agent calls mm_* tools  →  MCP Server  →  ws://127.0.0.1:3721  →  Magic Mouse  →  Windows OS

Inspired by Codex Computer Use and Agent-S: screenshot → reason → single action → verify → loop (≤30 steps).

Features

• 🐭 Desktop pet — Cursor isometric cube avatar, roam, drag, double-tap reactions
• 🖱️ Full computer use — screenshot, click, type, hotkey, scroll, drag, app launch, window focus
• 🤖 Cursor integration — auto Skill install, MCP registration, local token pairing
• 🛡️ Safety first — localhost-only Hub, audit log, approval gates, Ctrl+Shift+. emergency stop
• 💬 DeepSeek tab — optional on-device API chat in the pet panel
• 📋 Clipboard history, custom YAML actions, i18n UI

Quick start (developers)

npm run setup
npm run dev:mouse      # Vite :1420 + Hub :3721

Verify in Cursor:

用 Magic Mouse 查一下状态

See docs/使用文档.md for full usage, shortcuts, and FAQ.

Pet controls

Action	Effect
Click pet / tray icon	Open Magic Mouse panel
Double-click pet	Poke animation
Ctrl+Alt+P	Toggle panel
Drag pet	Move (position persisted)
Ctrl+Shift+.	Emergency stop
Ctrl+Shift+Y / N	Approve / deny pending action

Project layout

magic-skill/
├── apps/magic-mouse/       # Desktop pet (main user app)
├── apps/magic-launcher/    # Optional control console
├── packages/cursor-skill/  # SKILL.md + MCP server
├── scripts/                # setup, pair, shortcut, install-skill
├── docs/                   # User & developer docs
└── shared/                 # WebSocket protocol

Safety

• WebSocket binds to 127.0.0.1 only, token-authenticated
• Mutating actions logged to ~/.magic-skill/audit.log
• Destructive ops require user approval in the pet panel

Contributing & license

MIT License — see LICENSE. Bug reports and PRs welcome on Issues.

---

中文

Magic Skill 是什么？

Magic Skill 让 Cursor Agent 拥有操作你整台电脑的能力。它由两部分组成：

组件	作用	技术栈
Magic Mouse	Cursor 风格桌宠，在桌面上漫游、展示状态，并驱动真实鼠标键盘	Tauri 2 · Rust · Svelte
Magic Skill (MCP)	Cursor Skill + MCP 服务，向 Agent 暴露 17+ 个 mm_* 工具	Node 20+ · TypeScript · MCP SDK

你在 Cursor 说话  →  Agent 调用 mm_*  →  MCP Server  →  ws://127.0.0.1:3721  →  Magic Mouse  →  操作系统

设计思路融合 Codex Computer Use 与 Agent-S：截图 → 推理 → 单步动作 → 验证 → 循环（约 ≤30 步）。

核心功能

• 🐭 桌面宠物 — Cursor 立体方块形象，漫游、拖动、双击互动
• 🖱️ 完整 Computer Use — 截图、点击、输入、快捷键、滚动、拖拽、启动应用、聚焦窗口
• 🤖 Cursor 深度集成 — 自动安装 Skill、写入 MCP、本地令牌配对
• 🛡️ 安全可控 — 仅本机 Hub、审计日志、操作审批、Ctrl+Shift+. 紧急停止
• 💬 问 DeepSeek — 面板内可选的本机 API 对话
• 📋 剪贴板历史、YAML 自定义动作、中英界面

开发者快速开始

npm run setup
npm run dev:mouse      # Vite :1420 + Hub :3721

在 Cursor 聊天验证：

用 Magic Mouse 查一下状态

完整说明见 docs/使用文档.md。

桌宠操作

操作	效果
单击宠物 / 托盘图标	打开 Magic Mouse 面板
双击宠物	戳戳动画
Ctrl+Alt+P	打开/关闭面板
拖动宠物	移动位置（重启后记住）
Ctrl+Shift+.	紧急停止
Ctrl+Shift+Y / N	批准 / 拒绝待确认操作

目录结构

magic-skill/
├── apps/magic-mouse/       # 桌宠（主程序）
├── apps/magic-launcher/    # 可选控制台
├── packages/cursor-skill/  # SKILL.md + MCP 服务
├── scripts/                # 安装、配对、快捷方式
├── docs/                   # 用户与开发者文档
└── shared/                 # WebSocket 协议

安全说明

• WebSocket 仅绑定 127.0.0.1，令牌鉴权
• 修改类操作写入 ~/.magic-skill/audit.log
• 破坏性操作需在桌宠面板中批准

参与贡献

MIT 开源协议 — 详见 LICENSE。欢迎通过 Issues 反馈问题或提交 PR。

---

Made with ❤️ for Cursor users