Persona MCP Server

<p align="center"> <img src="./public/assets/avatar.png" alt="Persona" width="132" /> </p>

<h1 align="center">Persona</h1>

<p align="center"> <strong>让 AI 不只会回答，也能以角色的方式陪伴在桌面上。</strong> </p>

<p align="center"> 一个支持 VRM、VRMA、语音状态联动与 MCP 控制的跨平台桌面虚拟角色。 </p>

<p align="center"> <a href="https://github.com/staro1314/codex-persona/actions/workflows/ci.yml"><img src="https://github.com/staro1314/codex-persona/actions/workflows/ci.yml/badge.svg" alt="CI" /></a> <img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-4f7cff" alt="Windows, macOS and Linux" /> <img src="https://img.shields.io/badge/VRM%20%2F%20VRMA-supported-ff78b7" alt="VRM and VRMA supported" /> <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-35b779" alt="MIT License" /></a> </p>

<p align="center"> <img src="./docs/images/persona-client-showcase.webp" alt="Persona 中文客户端、模型库、实时预览与桌面悬浮角色" width="100%" /> </p>

<p align="center"> _{真实客户端效果：中文模型库、实时角色预览与透明置顶悬浮角色。画面中的模型由用户在本机导入，不随本仓库分发。} </p>

Persona 是什么？

Persona 是一个开源的桌面虚拟角色应用。它把本地 VRM 角色放到桌面最前端，并根据语音输出、待机策略或 AI 工具调用切换 VRMA 动作，让 Codex 等 AI 助手从“聊天窗口”变成有表情、有动作、有存在感的桌面伙伴。

它既可以独立运行，也可以通过本地 MCP 服务被 AI 控制。模型、动作和配置默认保存在本机；Persona 不录制麦克风、不保存音频、不转写内容，也不会把音频发送到网络。

成品能力

• 桌面悬浮角色：透明、置顶、可拖动、可缩放，并可调整悬浮区域，减少对下层页面点击的遮挡。
• VRM 模型库：导入多个 .vrm 模型，自定义名称、预览效果并切换默认角色。
• VRMA 动作库：支持待机、说话、思考、问候、开心、手枪手势、舞蹈及自定义动作卡片。
• 多动作编排：保留 VRMA 原文件名，支持拖动排序，并可选择固定片段、随机单次或持续轮询。
• 语音状态联动：监听受支持应用的播放进程，在说话开始与结束时自动切换角色动作。
• AI / MCP 控制：Codex 等 MCP 客户端可以播放动作、显示或隐藏角色，并读取运行状态。
• 中英文界面：客户端支持简体中文与英文切换。

<p align="center"> <img src="./docs/images/persona-settings-zh.webp" alt="Persona 中文设置界面、模型库与角色预览" width="100%" /> </p>

<p align="center"> _{中文设置界面：管理模型、预览角色、修改名称，并配置动作资源库。} </p>

它如何工作？

1. 在设置中导入一个本地 .vrm 模型。
2. 为待机、说话、思考等状态添加 .vrma 动作，并选择播放策略。
3. Persona 根据语音状态自动切换动作，或接受 MCP 客户端的显式控制。

角色窗口本身保持简洁：滚轮缩放，左键拖动旋转视角，右键拖动平移模型；窗口位置可通过拖动悬浮把手调整。

快速开始

环境要求：Node.js 24 或更高版本、npm，以及支持硬件加速的桌面环境。

git clone https://github.com/staro1314/codex-persona.git
cd codex-persona
npm install

Windows 和 macOS 首次从源码运行前，需要构建本地语音监听器：

npm run native:build
npm run native:test

启动 Persona：

npm run demo

首次启动会自动打开设置页。导入 .vrm 后，首个模型会成为默认模型；随后可以在动作库中添加 .vrma 文件。后台启动可使用：

npm start -- --background

仓库不会分发演示截图中的角色模型，也不会默认携带来源与授权不明确的 VRM / VRMA 资源。

连接 Codex

保持 Persona 运行，然后注册本地 MCP 服务：

codex mcp add persona --url http://127.0.0.1:47831/mcp

新建 Codex 会话后，可以直接尝试：

• “让 Persona 做一个开心动作。”
• “让角色进入思考状态。”
• “隐藏 Persona，完成后再显示。”
• “检查 Persona 和语音监听器是否正常运行。”

MCP 只开放 Persona 自身的显示、动作与状态能力，不会让客户端访问其他桌面内容。

动作与资源库

Persona 内置永久的待机与说话动作槽，也支持思考、问候、开心、手枪手势、舞蹈和自定义类型。每张动作卡片可以包含多个 VRMA 片段：

• 固定片段：正式运行时始终播放指定动作。
• 随机单次：每次进入该状态时随机选择一个动作。
• 持续轮询：停留在该状态期间，按当前顺序持续切换动作。

导入的资源与用户配置保存在 Persona 的本地应用数据中。打包资源保持只读；修改打包动作时会创建用户级覆盖，重置后可恢复原始配置。

如需制作可公开分发的资源包，请把模型放在 public/assets/models/，动作放在 public/assets/animations/，并在以下文件中登记：

public/assets/
├── library.json
├── library.json.example
├── manifest.json
├── manifest.json.example
├── models/
└── animations/

manifest.json 中必须填写来源、许可和分发状态。发布检查会拒绝来源不完整或未明确允许分发的资源。详见 资源许可说明。

平台支持

平台	自动语音输出监听	构建产物
Windows	WASAPI 进程级回环捕获	NSIS 安装包
macOS 14.2+	Core Audio Process Tap	DMG、ZIP（arm64 / x64）
Linux	PipeWire 进程流捕获	AppImage、DEB

Linux 需要在 PATH 中提供 pw-dump 和 pw-record；Windows 进程回环监听需要 Windows 10 build 20348 或更高版本；macOS 首次运行会请求“系统音频录制”权限。

每种监听器都只关注受支持应用的播放进程。Persona 不捕获麦克风，不生成语音，也不保存、转写或上传音频。

构建与开发

在目标操作系统上构建对应安装包：

npm run dist:windows
npm run dist:mac
npm run dist:linux

产物写入 release/。Windows 需要安装带 C++ 桌面开发工作负载的 Visual Studio Build Tools；macOS 需要 Xcode Command Line Tools 和 macOS 14.2+ SDK。

提交前可运行完整检查：

npm run check
npm run native:build
npm run native:test

更多资料：

• 架构与开发说明
• Codex 与集成 API
• 发布流程
• 安全策略

项目关系

本项目基于 xikhar/persona 持续扩展。本分支重点补充了中文国际化、模型与动作资源库、动作播放策略、可调桌面悬浮窗口、Windows 语音状态联动和 MCP 使用体验。

欢迎提交 Issue、改进动作类型、补充翻译，或分享你制作并拥有分发权的 VRM / VRMA 资源。

License

Persona 应用源码采用 MIT License。角色模型、动作和其他第三方素材不自动包含在该许可中，发布前请分别确认其使用与分发授权。