Skip to main content
Glama
lmy414

live2d-to-agent

by lmy414
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Live2D MCP

轻量的、可在 Agent 运行时让 Agent 接入控制的 Live2D 桌面宠物。

Agent 通过 MCP（Model Context Protocol）控制桌宠的表情、动作、模型和窗口设置，无需绑定特定 Live2D SDK。

架构

Agent (Claude / 任意 MCP 客户端)
  │  MCP JSON-RPC over STDIO
  ▼
packages/adapters/mcp   ← TypeScript MCP Adapter
  │  WebSocket :9228
  ▼
packages/desktop-pet    ← Python 桌宠 (PySide6 + OpenGL)
  │  live2d-py (用户自行安装)
  ▼
Live2D 模型渲染

消息流：Agent → MCP STDIO → Adapter → WebSocket → desktop-pet → Model API。

Related MCP server: Blockbench MCP

仓库结构

packages/
├── protocol/              # L2D 消息类型与 JSON Schema (传输无关)
├── adapters/mcp/          # MCP JSON-RPC STDIO Adapter → WebSocket 转发
└── desktop-pet/           # Python 桌面宠物 (基于 Live2DMascot, MIT)
    ├── app/               # 全局设置与版本定义
    ├── config/            # QConfig 持久化设置
    ├── control/           # WebSocket 服务 (:9228)
    ├── ui/                # Qt 窗口、系统托盘、设置面板
    ├── utils/             # 模型操作、model3.json 解析
    ├── Resources/         # 模型资源 (gitignore, 用户自行放入)
    ├── main.py            # 入口
    └── application.py     # 生命周期与组件编排

快速开始

前置条件

  • Node.js 20+

  • Python 3.13+ (64 位)

  • Windows（当前仅支持 Windows，因 live2d-py 提供 Win 平台 wheel）

1. 安装依赖

# TypeScript 侧
npm install

# Python 侧
cd packages/desktop-pet
pip install -r requirements.txt

live2d-py 不包含在本仓库中，由用户通过 pip install live2d-py 自行安装，以规避 Live2D 官方 SDK 分发许可。

2. 准备模型资源

模型文件不包含在仓库中。将 Live2D 模型放入 packages/desktop-pet/Resources/v3/：

Resources/v3/
├── Haru/
│   ├── Haru.model3.json    # 入口文件
│   ├── Haru.moc3
│   ├── Haru.physics3.json
│   ├── Haru.2048/           # 纹理
│   ├── expressions/         # 表情
│   ├── motions/             # 动作
│   └── sounds/              # 语音
├── Natori/
└── ...

3. 启动桌宠

cd packages/desktop-pet
python main.py

桌宠窗口出现后，WebSocket 服务在 ws://127.0.0.1:9228 监听。

4. 配置 MCP 客户端

方式 A：构建产物（推荐）

npm run build

在 MCP 客户端配置中指向构建产物：

{
  "mcpServers": {
    "live2d-pet": {
      "command": "node",
      "args": ["/absolute/path/to/live2d-mcp/packages/adapters/mcp/dist/index.js"]
    }
  }
}

方式 B：开发模式（tsx 直接运行 .ts）

用 node --import 加载 tsx loader，避免 npx tsx 在后台进程中解析失败：

{
  "mcpServers": {
    "live2d-pet": {
      "type": "stdio",
      "command": "node",
      "args": [
        "--import",
        "file:///absolute/path/to/live2d-mcp/node_modules/tsx/dist/loader.mjs",
        "/absolute/path/to/live2d-mcp/packages/adapters/mcp/src/index.ts"
      ],
      "env": {}
    }
  }
}

也可通过 Claude CLI 添加（添加后仍需检查路径是否为绝对路径）：

claude mcp add live2d-pet -- \
  node \
  --import file:///absolute/path/to/live2d-mcp/node_modules/tsx/dist/loader.mjs \
  /absolute/path/to/live2d-mcp/packages/adapters/mcp/src/index.ts

配置注意事项

#

错误做法

问题

正确做法

1

手动创建 ~/.claude/.mcp.json

.mcp.json 是项目级配置，全局 MCP 服务器不读这个文件

全局配置写在 ~/.claude.json 顶层 mcpServers 中

2

用 npx tsx 作为 command

npx 在 Claude 后台进程中可能解析失败

用 node --import <tsx loader 绝对路径> 替代

3

使用相对路径 src/index.ts

无 cwd 时从用户主目录解析，找不到文件

所有路径用绝对路径

4

在配置中设置 cwd 字段

Claude 的 MCP 启动器不支持 cwd，设置无效

所有路径用绝对路径

配置后重启 MCP 客户端，Agent 即可通过 7 个工具控制桌宠。

MCP 工具

工具

参数

说明

model_load

path

加载指定路径的模型，返回表情列表

expression_list

—

列出当前模型的可用表情

expression_set

name

切换到指定表情

action_list

—

列出可用的语义动作

action_perform

name

播放指定动作

settings_get

—

读取窗口、模型、音频、场景设置

settings_set

键值对

修改设置（如 model.scale、window.width）

开发

# 类型检查与构建
npm run check
npm run build

# 运行测试
npm test

# WebSocket 层测试
python scripts/test_websocket.py

# MCP 闭环测试
node scripts/test_mcp.mjs

技术债

详见 TECH_DEBT.md。当前已知：

  • TD-001：点击模型触发 Touch 方法报错（PyPI 版 live2d-py API 缺失），留到 AvatarRuntime 适配层修复。

许可

  • 本项目代码采用 MIT 协议。

  • packages/desktop-pet/ 基于 Live2DMascot（MIT, by Arkueid）fork。

  • Live2D Cubism SDK 及模型文件 不包含在本仓库中，受 Live2D 官方许可条款 约束，由用户自行获取与安装。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers

  • OmniFlow

    huppugo1
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI clients to automate Windows desktop applications through window manipulation, image recognition, OCR, keyboard/mouse simulation, and memory operations via the MCP protocol.
    MIT

  • pov

    empezarcero
    A
    license
    A
    quality
    D
    maintenance
    Enables LLM agents to capture screenshots, control mouse/keyboard, and manage windows on desktop platforms, primarily Windows, via an MCP server.
    16
    1
    MIT

  • Emotion MCP

    yoshiomiyamae
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that enables AI assistants to switch character portraits (2D images or VRM 3D models) based on emotion, with support for multiple transitions and real-time updates via WebSocket.
    9 npm
    1
    AGPL 3.0