Desktop Mascot MCP

桌面吉祥物MCP

日本语 | 英语

______________________________________________________________________

是与MCP（Model Context Protocol）对应的AI工具联合，3D登场人物常驻桌面的吉祥物应用程序。

AI回答的话，角色语音、唇音、表情、手势进行动态观察时的轴心点。

这是什么？

MCP服务器是向AI工具（Claude Desktop、Cursor等）添加功能的程序。当我们引入这个项目时 speak 的命令，3D角色一边说话一边移动。

あなた → AI ツール → speak コマンド → キャラクターが音声・アニメーションで返答

有关MCP的详细信息： 模型上下文协议

______________________________________________________________________

✨ 机能

• 音声合成：通过VOICEVOX兼容API（VOICEVOX/AivisSpeech/CoEIROINK等）进行声音再生
• 唇形水槽：配合声音自然的嘴的动作
• 表情：6种类の感情表现（neutral / happy / sad / angry / surprised / relaxed）
• 手势：VRMA格式的动画，例如wave/nod/shake/think
• 偶像：放置期间自动播放随机动画
• 透明窗口：始终融入桌面的顶层窗口
• 状态记忆：自动保存相机位置窗口位置

______________________________________________________________________

📋 需要的东西

需要的东西 |---|---| | Node.js 18 以上 | | |Git| git-scm.com | 支持MCP的AI工具 克劳德桌面版 按钮关闭对话框 VOICEVOX兼容语音合成引擎 VRM模型文件（.vrm）｜参照下述｜

按OS支持语音合成引擎

引擎｜Windows｜macOS｜Linux｜ |---|---|---|---| | Aivis演讲 | ✅ | ❌ | ❌ | | VOICEVOX | ✅ | ✅ | ✅ | | COEIROINK 公司 | ✅ | ❓ | ❓ |

获得电压调节模块型号

此存储库不包含电压调节模块模型。请另外准备您喜欢的VRM机型。

免费机型示例：

• 尼科尼立体“艾丽西亚实体” - 商用利用可
• VRoid轮毂 -按模型查看分发条件

______________________________________________________________________

🚀 安装，安装

初次见面：更简单的步骤是 入门 来修改标记元素的显示属性。

1.克隆存储库

git clone https://github.com/rennosuke-haresu/desktop-mascot-mcp.git
cd desktop-mascot-mcp
npm install

2.放置电压调节模块模型

已下载 .vrm 打开文件 assets/models/ 的下界。

desktop-mascot-mcp/
└── assets/
    └── models/
        └── YourModel.vrm   ← ここに置く

3.创建配置文件

config.example.json 复制 config.json 来修改标记元素的显示属性。

cp config.example.json config.json

config.json 中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。

{
  "vrm": {
    "modelPath": "./assets/models/YourModel.vrm"
  }
}

其他的设定即使保持原样也会移动。设置详细信息来修改标记元素的显示属性。

4.构建

npm run build:electron

5.启动语音合成引擎

启动VOICEVOX兼容的语音合成引擎。启动确认：

# VOICEVOX の場合（デフォルト: 50021番ポート）
curl http://127.0.0.1:50021/version

# AivisSpeech の場合（デフォルト: 10101番ポート）
curl http://127.0.0.1:10101/version

6.启动电压调节模块窗口

npm run start:electron

透过窗口显示，角色出现在画面上。

7.MCP客户端注册

在AI工具的设置文件中追加以下内容。

对于Claude Desktop 配置文件位置：

• 窗户： %APPDATA%\Claude\claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "desktop-mascot-mcp": {
      "command": "node",
      "args": ["/path/to/desktop-mascot-mcp/dist/index.js"],
      "env": {
        "VOICEVOX_SPEAKER_ID": "888753760",
        "VOICEVOX_BASE_URL": "http://127.0.0.1:10101"
      }
    }
  }
}

/path/to/desktop-mascot-mcp/ 将条目添加到文档注册表。 Windows示例： C:/Users/yourname/desktop-mascot-mcp/dist/index.js

Cursor/其他支持MCP的工具

与各工具的MCP服务器设置相同 command / args / env 中所述修改相应参数的值。

8.重新启动AI工具

重新启动AI工具以反映设置。MCP服务器将自动启动。

______________________________________________________________________

💬 用法

让角色说话

在AI工具的聊天中对话的话，根据自定义命令的设定角色会自动反应。

自定义指令的设置示例（例如，Claude Desktop的项目设置）

ユーザーに返答した後、必ず speak ツールを呼び出してください。
- text: 返答内容（日本語）
- emotion: 感情（neutral / happy / sad / angry / surprised / relaxed）
- animation: ジェスチャー（wave / nod / shake / think / clap など）

speak 工具参数

｜参数｜必需｜说明｜ |---|---|---| | text | ✅ | 要读的文本 | emotion | - | 表情（中立/快乐/悲伤/愤怒/惊讶/放松）| | animation 动画名称（在animations.json中定义）

窗口操作

鼠标拖动，相机旋转 缩放鼠标滚轮 窗口拖动 | Ctrl + , ｜通常模式↔ 设置模式的切换

“相机位置”窗口位置将自动保存，并在下次启动时恢复。

通常模式和设定模式

Ctrl + , 中所述修改相应参数的值。

｜正常模式（默认）｜设置模式｜ |---|---|---| 背景｜透明｜不透明（深灰色）｜ ｜窗格｜无｜有｜ |常时最前面|✅ | ❌ | ｜任务栏｜隐藏｜显示｜

设置模式将条目添加到文档注册表。调整尺寸后 Ctrl + , 中所述修改相应参数的值。

______________________________________________________________________

⚙️ 设定

config.json 中所述修改相应参数的值。更改后 npm run build:electron 中所述修改相应参数的值。

{
  "vrm": {
    "modelPath": "./assets/models/YourModel.vrm"
  },
  "animations": {
    "configPath": "./assets/animations/animations.json"
  },
  "camera": {
    "position": { "x": 0, "y": 1.3, "z": -1.5 },
    "lookAt":   { "x": 0, "y": 1.2, "z": 0 },
    "fov": 45
  },
  "window": {
    "storagePrefix": "desktop-mascot"
  }
}

相机设置提示: camera.lookAt.y 与模型的脸部高度一致时，脸部会显示在窗口中央。

环境变数

｜变量名｜默认｜说明｜ |---|---|---| | VOICEVOX_BASE_URL | http://127.0.0.1:10101 音频合成API的URL | VOICEVOX_SPEAKER_ID | 888753760 ｜说话人ID（因引擎而异）｜

请在使用的语音合成引擎的UI和API中确认说话者ID。

每个引擎的默认URL: 引擎URL |---|---| |VOICEVOX| http://127.0.0.1:50021 | |Aivis演讲| http://127.0.0.1:10101 | COEIROINK | http://127.0.0.1:50031 |

添加动画

动画是 VRMA 形式（.vrma），模板名称将采用不同的格式。

如何获取VRMA文件

方法1:直接下载VRMA文件（最简单）

展位 发布和销售了很多VRMA文件。

• VRoid官方免费发布（寒暄、姿势等7种）
• 还有很多其他创作者分发的作品

方法2:从FBX转换（例如Mixamo）

米克萨莫（如果有Adobe账号的话免费）等FBX动画可以转换为VRMA。

*方法2a:CLI工具转换（无需Blender）*

fbx2vrma转换器 来定义自定义外观。

node fbx2vrma-converter.js -i input.fbx -o output.vrma

从Mixamo下载时：

• 格式： FBX
• 皮肤： 无皮的（仅限骨架）
• 每秒帧数： 30
• 关键帧缩减： 无

*方法2b：使用Blender进行转换*

搅拌机 + 搅拌机VRM插件 的方法。

1. 在Blender上安装并启用VRM Add-on（編集 → プリファレンス → アドオン）
2. 导入电压调节模块模型（ファイル → インポート → VRM (.vrm)）
3. 导入Mixamo的FBX动画（ファイル → インポート → FBX (.fbx)）
4. 将动画重定位到VRM骨骼结构
5. 以VRMA格式导出（ファイル → エクスポート → VRM Animation (.vrma)）

了解更多信息 VRM官方文档 来修改标记元素的显示属性。

方法3:自己创建动画

• 搅拌机 + 搅拌机VRM插件：无料
• VRM定位桌面（Steam）：收费、操作简单

______________________________________________________________________

注册animations.json

无动画：如果不准备动画文件，或者 idle 如果未注册动画，角色将以手臂稍微放下的自然姿势显示。

将VRMA文件 assets/animations/ 放置 animations.json 的双曲正切值。 animations.example.json 中所述修改相应参数的值。

cp assets/animations/animations.example.json assets/animations/animations.json

{
  "animations": [
    {
      "name": "wave",
      "file": "wave.vrma",
      "loop": false,
      "fadeTime": 0.3,
      "returnToIdle": true,
      "category": "gesture",
      "description": "手を振る"
    }
  ]
}

｜字段｜说明｜ |---|---| | name 动画名称（speak 工具 animation 在参数中指定的名称）｜ | file VRMA文件名（assets/animations/ 相对路径 | loop 是否循环播放 | fadeTime 到下一个动画的淡入时间（秒） | returnToIdle 播放后返回偶像动画吗 | category | gesture / idle 中的任一个

______________________________________________________________________

⚠️ 故障排除

不播放声音

• 确认语音合成引擎是否启动（端口因引擎而异）
• VOICEVOX_SPEAKER_ID 确认引擎是否有效
• 检查MCP服务器日志：

- 窗户： %APPDATA%\Claude\logs\mcp-server-desktop-mascot-mcp.log - macOS： ~/Library/Logs/Claude/mcp-server-desktop-mascot-mcp.log

未显示角色

• npm run start:electron 确认是否在启动电压调节模块窗口
• config.json 的，之 vrm.modelPath 确认是否正确
• 在窗口的DevTools中确认错误（Ctrl+Shift+I）

未检测到MCP服务器

• dist/index.js 确认是否存在（npm run build:electron 执行）
• 确认配置文件的JSON是否正确（注意末尾逗号等）
• 完全重新启动AI工具

动画无法移动

• VRMA文件 assets/animations/ 确认是否存在
• animations.json 确认的文件名和实际文件名是否一致
• 在DevTools控制台上 [desktop-mascot-mcp] Found N animation configs 查看日志

______________________________________________________________________

📄 许可证

源代码是 MIT许可证 中所述修改相应参数的值。了解更多信息 许可证.md 来修改标记元素的显示属性。

关于资源：存储库中不包含VRM模型或动画文件。 您自己准备的文件请根据各自的分发许可证使用。

______________________________________________________________________

🙏 谢辞

• VOICEVOX / Aivis演讲 -语音合成引擎
• 模型上下文协议 -MCP-SDK
• @pixiv/three vrm - VRM 実装
• Three.js -三维渲染
• 米克萨莫 -动画数据

______________________________________________________________________

______________________________________________________________________

桌面吉祥物MCP

一个桌面吉祥物应用程序，在您的桌面上显示一个3D角色，对您的AI工具的响应做出反应 语音、唇形同步、表情和手势 通过MCP（模型上下文协议）。

这是什么？

一 MCP服务器 是一个用新功能扩展人工智能工具（Claude Desktop、Cursor等）的程序。通过整合这个项目，你的人工智能工具可以调用 speak 命令使3D角色说话并相应地制作动画。

You → AI tool → speak command → Character responds with voice & animation

了解有关MCP的更多信息： 模型上下文协议

______________________________________________________________________

✨ 特性

• 语音合成：通过VOICEVOX兼容API（VOICEVOX/AivisSpeech/COEIROINK等）播放
• 嘴唇同步：与语音同步的自然嘴部运动
• 表达：6种情绪类型（中性/快乐/悲伤/愤怒/惊讶/放松）
• 手势：VRMA动画支持（波浪/点头/摇晃/思考等）
• 空闲动画：空闲时随机播放动画
• 透明的窗户：始终位于与桌面融为一体的顶部窗口
• 状态持久性：相机和窗口位置会自动保存

______________________________________________________________________

📋 需求

TTS引擎与操作系统的兼容性

获取VRM模型

此存储库中不包含VRM模型。请自行准备。

免费模型示例：

• 尼科尼固体“艾丽西娅固体” -商业上可用
• VRoid轮毂 -检查每个型号的许可证

______________________________________________________________________

🚀 设置

新来的？ 有关简化的演练，请参见 入门指南.

1.克隆存储库

git clone https://github.com/rennosuke-haresu/desktop-mascot-mcp.git
cd desktop-mascot-mcp
npm install

2.放置VRM模型

把你的 .vrm 文件在 assets/models/.

desktop-mascot-mcp/
└── assets/
    └── models/
        └── YourModel.vrm   ← place here

3.创建配置文件

复制 config.example.json 到 config.json.

cp config.example.json config.json

打开 config.json 并设置VRM模型路径。

{
  "vrm": {
    "modelPath": "./assets/models/YourModel.vrm"
  }
}

其他设置可以开箱即用。看 配置 了解详情。

4.建造

npm run build:electron

5.启动TTS发动机

启动与VOICEVOX兼容的TTS引擎。验证它是否正在运行：

# VOICEVOX (default port: 50021)
curl http://127.0.0.1:50021/version

# AivisSpeech (default port: 10101)
curl http://127.0.0.1:10101/version

6.启动VRM窗口

npm run start:electron

屏幕上将出现一个透明窗口，显示您的角色。

7.注册为MCP服务器

将以下内容添加到AI工具的配置文件中。

克劳德桌面版

配置文件位置：

• 窗户： %APPDATA%\Claude\claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "desktop-mascot-mcp": {
      "command": "node",
      "args": ["/path/to/desktop-mascot-mcp/dist/index.js"],
      "env": {
        "VOICEVOX_SPEAKER_ID": "888753760",
        "VOICEVOX_BASE_URL": "http://127.0.0.1:10101"
      }
    }
  }
}

替换 /path/to/desktop-mascot-mcp/ 与实际路径。 Windows示例： C:/Users/yourname/desktop-mascot-mcp/dist/index.js

光标/其他MCP兼容工具

使用相同的 command / args / env 在每个工具的MCP服务器设置中。

8.重新启动AI工具

重新启动AI工具以应用设置。MCP服务器将自动启动。

______________________________________________________________________

💬 用法

让角色说话

当你使用人工智能工具聊天时，角色会根据你的自定义指令自动做出反应。

自定义指令示例（例如Claude Desktop项目设置）

After responding to the user, always call the speak tool with:
- text: your response text
- emotion: emotion type (neutral / happy / sad / angry / surprised / relaxed)
- animation: gesture name (wave / nod / shake / think / clap, etc.)

speak 刀具参数

窗口控件

相机和窗口位置会自动保存，并在下次启动时恢复。

正常模式和设置模式

按 Ctrl + , 在模式之间切换。

设置模式 显示一个窗口框架，以便您可以正常调整大小并与窗口交互。调整大小后，按 Ctrl + , 以返回正常模式。

______________________________________________________________________

⚙️ 配置

编辑 config.json 自定义设置。重建与 npm run build:electron 更改后。

{
  "vrm": {
    "modelPath": "./assets/models/YourModel.vrm"
  },
  "animations": {
    "configPath": "./assets/animations/animations.json"
  },
  "camera": {
    "position": { "x": 0, "y": 1.3, "z": -1.5 },
    "lookAt":   { "x": 0, "y": 1.2, "z": 0 },
    "fov": 45
  },
  "window": {
    "storagePrefix": "desktop-mascot"
  }
}

相机提示：设置 camera.lookAt.y 将模型的面部高度调整到窗口的中心。

环境变量

检查TTS引擎的UI或API以找到正确的扬声器ID。

按引擎列出的默认URL:

添加动画

动画使用 VRMA格式 (.vrma).

获取VRMA文件

选项1：直接下载VRMA文件（最简单）

展位 有许多VRMA文件可供免费或购买。

• 官方VRoid免费包 （问候语、姿势、7种类型）
• 许多其他可用的创建者包

选项2：从FBX转换（例如Mixamo）

您可以从以下格式转换FBX动画 米克萨莫 （使用Adobe帐户免费）转换为VRMA。

*选项2a：通过CLI转换（不需要Blender）*

使用 fbx2vrma转换器 仅支持Node.js。

node fbx2vrma-converter.js -i input.fbx -o output.vrma

从Mixamo下载时：

• 格式： FBX
• 皮肤： 无皮的 （仅骨骼）
• 每秒帧数： 30
• 关键帧缩减： 无

*选项2b：通过Blender转换*

使用 搅拌机 + 搅拌机VRM插件.

1. 安装并启用VRM插件(Edit → Preferences → Add-ons)
2. 导入VRM模型(File → Import → VRM (.vrm))
3. 导入Mixamo FBX动画(File → Import → FBX (.fbx))
4. 将动画重定向到VRM骨骼结构
5. 导出为VRMA(File → Export → VRM Animation (.vrma))

请参阅 VRM官方文件 了解更多详情。

选项3：创建自己的动画

• 搅拌机 + 搅拌机VRM插件：免费
• VRM定位桌面 （Steam）：付费，更易于使用

______________________________________________________________________

在animations.json中注册

没有动画？ 如果没有提供动画文件，或者如果没有 idle 动画注册后，角色将以自然的休息姿势站立。

将VRMA文件放入 assets/animations/ 并将其注册到 animations.json. 您可以复制 animations.example.json 作为一个起点。

cp assets/animations/animations.example.json assets/animations/animations.json

{
  "animations": [
    {
      "name": "wave",
      "file": "wave.vrma",
      "loop": false,
      "fadeTime": 0.3,
      "returnToIdle": true,
      "category": "gesture",
      "description": "Wave hand"
    }
  ]
}

______________________________________________________________________

⚠️ 故障排除

无音频播放

• 确认您的TTS发动机正在运行（端口因发动机而异）
• 验证 VOICEVOX_SPEAKER_ID 适用于您的发动机
• 检查MCP服务器日志：

- 窗户： %APPDATA%\Claude\logs\mcp-server-desktop-mascot-mcp.log - macOS： ~/Library/Logs/Claude/mcp-server-desktop-mascot-mcp.log

角色未显示

• 确认VRM窗口正在运行 npm run start:electron
• 验证 vrm.modelPath 在 config.json 是正确的
• 检查窗口的DevTools中的错误(Ctrl+Shift+I)

无法识别MCP服务器

• 确认 dist/index.js 存在（运行 npm run build:electron)
• 验证配置JSON（注意尾随逗号）
• 完全重启您的AI工具

动画未播放

• 确认VRMA文件存在于 assets/animations/
• 检查中的文件名 animations.json 匹配实际文件
• 寻找 [desktop-mascot-mcp] Found N animation configs 在DevTools控制台中

______________________________________________________________________

📄 许可证

源代码在 MIT许可证。参见 许可证.md 了解详情。

关于资产：VRM模型和动画文件不包含在此存储库中。 您自己提供的文件受其各自的分发许可证的约束。

______________________________________________________________________

🙏 积分

• VOICEVOX / Aivis演讲 -TTS发动机
• 模型上下文协议 -MCP-SDK
• @pixiv/three vrm -VRM实现
• Three.js -3D渲染
• 米克萨莫 -动画数据