Emotion MCP

情绪MCP

AI助手是可以根据自己的感情切换立绘的MCP（Model Context Protocol）服务器。

動作画面 動作画面

管理画面 管理画面 設定画面

特徴

• 二维图像模式：上传立绘图像切换表情
• VRM三维模型模式：通过混合变形对VRoid/VRM格式的三维模型进行表情控制
• 多种过渡：6种效果，包括淡入、滑动、缩放和摇动
• 实时更新：通过WebSocket立即切换表情
• 空闲动画：VRM模式下的眨眼、呼吸自动动画
• 高速动作：使用Bun的爆速启动、执行

体系结构

┌─────────────────┐
│  Claude Code    │ AIが表情を選択
│  (AI Assistant) │ change_expression("embarrassed", "fade")
└────────┬────────┘
         │ MCP Protocol (stdio)
┌────────▼────────┐
│   MCP Server    │ ツール実装
│  (TypeScript)   │ list_expressions, change_expression
└────────┬────────┘
         │ HTTP API
┌────────▼────────┐
│   HTTP Server   │ WebSocket経由でクライアントに通知
│  (Bun)          │
└────┬───────┬────┘
     │       │
┌────▼────┐ ┌▼─────────┐
│ Admin   │ │ Viewer   │  2D画像 or VRM 3Dモデル
│ UI      │ │          │  (Three.js + @pixiv/three-vrm)
└─────────┘ └──────────┘

安装，安装

1.安装相关性

bun install

2.MCP服务器设置

根据您使用的环境，请添加到以下配置文件之一：。

克劳德代码（CLI/VCode拡張）

配置文件: ~/.claude.json

{
  "mcpServers": {
    "emotion-mcp": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/emotion-mcp/src/server/index.ts"]
    }
  }
}

克劳德桌面

配置文件位置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "emotion-mcp": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/emotion-mcp/src/server/index.ts"]
    }
  }
}

※ /absolute/path/to/emotion-mcp 请用实际路径替换

3.启动Claude Code/Claude Desktop

启动（或重新启动）Claude Code或Claude Desktop以反映设置。

当MCP服务器启动时：

• HTTP服务器自动在端口3000上启动
• 查看器自动在浏览器中打开

手动访问以下URL：

• 管理UI: http://localhost:3000/admin
• 查看器：http://localhost:3000/viewer

提示：

• 禁用自动打开查看器：

  AUTO_OPEN_VIEWER=false

• 更改端口号：

  {
    "mcpServers": {
      "emotion-mcp": {
        "command": "bun",
        "args": ["run", "/absolute/path/to/emotion-mcp/src/server/index.ts"],
        "env": {
          "PORT": "8080"
        }
      }
    }
  }

默认值为3000。如果更改 http://localhost:8080/admin 来定义自定义外观。

4.立绘的注册

二维图像模式（默认）

1. http://localhost:3000/admin访问
2. 确认模式切换为“2D图像”
3. 通过拖放或单击上传图像
4. 输入表情名（英文数字）和显示名
5. 设置默认表情

VRM三维模型模式

1. http://localhost:3000/admin访问
2. 在模式切换中选择“VRM 3D”
3. 通过拖放或单击上传VRM文件（.vrm）
4. 上传后，显示从模型中检测到的混合变形列表
5. 使用“新建预设”按钮创建预设

- 输入预设名称（AI使用的名称）和显示名称 - 使用每个混合变形滑块调整表情权重

1. 设置默认预设

用法

管理UI

二维模式：

• 上传：通过拖放或单击添加图像
• 默认设置：选择要初始显示的表情
• 削除：删除不需要的表情

电压调节模块模式：

• 模型上传：上载.vrm文件
• 创建预设：使用混合变形滑块调整和保存表情
• 编辑/删除预设：更改或删除现有预设
• 默认设置：选择要初始显示的预设

从AI改变表情

与Claude Code对话时，AI会自动更改表情：

AI: べ、別にあんたのために説明したわけじゃないんだからね！
    [change_expression("embarrassed", "quick-fade")]

无论是二维还是VRM模式，MCP工具的界面都是相同的。根据在管理UI中设置的模式，可以切换图像或更改混合变形。

可用工具

list_expressions

获取已注册的表情列表。在二维模式下返回图像表情，在VRM模式下返回预设列表。

list_expressions()

change_expression

更改表情。

change_expression({
  expression: "embarrassed",  // 表情名（2D）またはプリセット名（VRM）
  transition: "fade",          // トランジション（省略可）
  duration: 300                // 時間（ms、省略可）
})

可用过渡：

｜过渡｜说明｜ |---|---| | fade ｜正常淡入（默认）｜ | quick-fade 快速淡入 | slide 滑动进入 | zoom 放大 | shake 振动（动摇） | instant 立即切换

get_current_expression

获取当前显示的表情。

get_current_expression()

VRM三维模型详细信息

支持的格式

• VRM0.x（VRoid Studio旧版本等）
• VRM 1.0（VRoid Studio最新版等）

混合变形

自动检测包含在VRM模型中的混合变形（表情变形）。常见的VRM模型包括以下混合变形：

• happy, angry, sad, relaxed, surprised （基本表情）
• blink, blinkLeft, blinkRight （眨眼）
• aa, ih, ou, ee, oh （唇部水槽）

空闲动画

在VRM模式下，以下空闲动画将自动运行：

• 眨眼：以3～7秒的随机间隔自然的眨眼
• 呼吸：胸骨的微小规模变化引起的呼吸动作（约4秒周期）
• 自然的站立姿势：从T形姿势自动转换为手臂放下的自然姿势

相机操作（鼠标）

在电压调节模块模式下，鼠标可以自由操纵相机：

向左拖动，旋转相机 向右拖动，平移 缩放控制盘

导入模型时，相机将自动调整为面部高度。

技术栈

• Three.js -三维渲染（无需通过CDN构建步骤）
• @pixiv/three vrm -导入和控制电压调节模块模型
• 通过导入映射导入ES模块

推荐的表情名称

AI容易理解的表情名的例子：

• normal: 通常
• happy：很高兴
• sad：悲伤
• angry：愤怒
• embarrassed害羞
• surprised：惊喜
• worried: 心配
• thinking：正在考虑
• confident: 自信満々

故障排除

查看器无法自动打开

如果在HTTP服务器启动时无法自动打开查看器：

1. 手动http://localhost:3000/viewer的双曲正切值
2. 如果出现找不到浏览器的错误，请在环境变量中禁用并手动打开

无法连接到WebSocket

1. 确认HTTP服务器是否启动
2. 在浏览器控制台中检查错误
3. 确定端口3000是否被其他应用程序使用

未显示MCP工具

1. 确认配置文件的路径是否正确
2. Claude Code / Claude Desktopを再起动
3. 检查MCP服务器的日志（stderr输出）

表情不变

1. 确认是否打开查看器页面
2. 确定WebSocket的连接状态（右上绿色指示器）
3. 在浏览器控制台中检查错误

未显示电压调节模块模型

1. 确认.vrm文件是否为正确的VRM格式
2. 确认浏览器是否支持WebGL
3. 在浏览器控制台中检查Three.js错误
4. 如果模型文件太大，请在VRoid Studio中优化并重新导出

Windows注意事项

首次启动时可能会出现Windows防火墙对话框。HTTP服务器接入网络所需，请允许。

开発

项目结构

emotion-mcp/
├── src/
│   ├── server/              # バックエンド
│   │   ├── index.ts         # MCPサーバー
│   │   ├── http-server.ts   # HTTPサーバー
│   │   └── storage.ts       # データ永続化
│   ├── client/              # フロントエンド
│   │   ├── admin/           # 管理UI
│   │   └── viewer/          # 表示用クライアント
│   │       ├── app.js       # メインアプリ（2D/VRMモード分岐）
│   │       └── vrm-renderer.js  # VRM 3Dレンダラー
│   └── shared/              # 共通型定義
├── data/                    # データディレクトリ
│   ├── config.json          # 設定（モード、2D表情）
│   ├── vrm-config.json      # VRM設定（プリセット）
│   ├── expressions/         # 2D立ち絵画像
│   └── vrm/                 # VRMモデルファイル
└── package.json

脚本

# HTTPサーバー起動（開発用）
bun run dev:http

# MCPサーバー起動（テスト用）
bun run dev

# ビルド
bun run build

许可证

麻省理工学院

作者

与克劳德代码和你一起创建