qianyiai/kurocat
系统工具一款置顶透明桌宠,实时显示键盘敲击和鼠标按键,可切换 6 款猫咪皮肤,并能通过 MCP 用 AI 定制外观。
项目介绍
KuroCat 是一个 Windows 和 macOS 上的透明置顶桌面伴侣,用猫咪形象实时反馈键鼠操作:打字时猫头上方弹出立体键帽,左键、右键和中键分别高亮并显示 LMB/RMB 小气泡,猫的头部会随敲击节奏歪头,空闲一侧的爪子自动蜷起。
它内置经典小黑猫、布偶猫、橘猫、三花、奶牛猫和暹罗猫 6 款手绘皮肤,可在 65% 紧凑键盘和 108 键全尺寸布局之间切换,也能在「面向观众」和「面向猫咪」两种视角之间切换。程序内置 MCP 服务端,AI 客户端可以按描述新增或修改毛色、花纹、耳朵、瞳色、尾巴、白手套、高亮色和自定义斑块,改完直接热更新到桌面。
实现上使用 Tauri v2,由 Rust 全局原生钩子采集键鼠事件,界面用 HTML5 Canvas 绘制,官方称不需要额外运行时依赖。
快速使用
Windows 10/11 用户从 Releases 下载并运行 v4.6.2 x64 安装包。安装后会创建桌面快捷方式、开始菜单项和卸载入口。老版 Windows 10 或 LTSC 精简镜像如果缺少 WebView2,需要用管理员权限运行微软的 WebView2 引导程序;不支持 Windows 7。
macOS 11+ 用户下载 v4.5.0 通用版 DMG,把 KuroCat.app 拖入「应用程序」后运行。由于应用未公证,如果系统提示「无法验证开发者」或「已损坏」,按 README 在终端执行一次 xattr -cr /Applications/KuroCat.app。随后在「系统设置 → 隐私与安全性」中为 KuroCat 同时勾选辅助功能和输入监控权限。
桌宠运行后接入 AI 客户端:
- 右键猫咪,勾选 「开启 MCP 扩展」,点击 「复制 MCP 配置」。
- 把配置粘贴到 Claude Desktop、Cursor、Antigravity、Windsurf 或 Cline 的 MCP 配置中。
- Stdio 模式把
command指向已安装的程序,args设为["----mcp"]。 - HTTP 模式在桌宠运行时连接本机地址
http://127.0.0.1:27420/mcp。
Stdio 配置示例:
{
"mcpServers": {
"kurocat": {
"command": "C:\\Users\\<你的用户名>\\AppData\\Local\\KuroCat\\KuroCat.exe",
"args": ["--mcp"]
}
}
}
然后让 AI 调用 upsert_cat 等工具新增猫咪,新外观无需重启即可出现在桌面。自定义皮肤保存在 Windows 的 %APPDATA%\kuro-cat-pet\cats.json 或 macOS 的 ~/Library/Application Support/kuro-cat-pet/cats.json,手动编辑也会自动热重载。
本地构建
需要 Windows 10/11 或 macOS 11+、Node.js 18+,以及带 cargo 的 Rust 工具链。克隆仓库后执行:
npm install
npm run tauri:dev # 本地热更新调试
npm run tauri:build # 编译 Release 与安装包
使用约束
- 支持 Windows 10/11 和 macOS 11+,macOS 包为 Apple Silicon 与 Intel 通用版;明确不支持 Windows 7。
- macOS 上监听键盘和鼠标需要授予辅助功能与输入监控权限;覆盖升级后如果权限不生效,可能需要在列表里移除后重新添加。
- 全屏或无边框游戏可能需要锁定鼠标穿透,用
Alt解锁;强内核反作弊网游可能需要从托盘暂停监听。 - MCP 的 HTTP 服务监听本机
127.0.0.1:27420,只在桌宠运行时可用。 - 项目采用 MIT 许可证。
HotRepo 点评
KuroCat 于 2026-11-22 进入 HotRepo 的 TypeScript 新项目榜:在 16:16 至 17:16 UTC 约一小时的统计窗口内新增 14 颗 Star,累计 117 颗;记录的 Star 采样在半小时内从 111 升到 117。观察窗口很短,这只能说明早期关注度,不足以判断持续趋势。技术上比较特别的是把 MCP 服务端放在桌宠进程内,而不是另起一个进程,因此已有的 AI 客户端可以在桌宠运行时直接改外观。需要留意的实际问题是分发方式:主要交付物是预编译可执行文件,而现有材料无法确认发布者身份,也无法确认这些二进制文件与仓库源码的对应关系。
本文由 AI 根据项目公开资料和 HotRepo 的记录撰写,更新于 ,以项目官方文档为准。