MCP-плагин (Model Context Protocol) для редактора Unity, ориентированный на разработку моделей VRChat.
Через встроенный HTTP-сервис (JSON-RPC 2.0 / SSE) предоставляет внешним AI-агентам 49 инструментов, охватывающих:
Стандартные возможности проекта Unity: информация о проекте, запрос и редактирование сцен/объектов/компонентов, управление ассетами, диагностика журнала консоли (в соответствии с возможностями manage_scene / manage_gameobject / manage_asset / manage_editor существующих плагинов типа unity-mcp);
Специальные возможности VRChat: детальный отчёт об аватаре (меню / параметры / привязки / производительность / использование ресурсов / установленные плагины), редактирование параметров компонентов, таких как MA / VRCFury, создание, копирование, редактирование и привязка файлов меню выражений и параметров выражений.
Реализация на чистом C#, ноль сторонних зависимостей (не используются никакие библиотеки, такие как Python / JS / Newtonsoft.Json), совместим с Unity 2022.3 и Unity 6 (редакторы Windows / macOS / Linux).
Related MCP server: unityxclaude
Возможность | Описание |
HTTP-сервис на порту | Встроенный HTTP/1.1-сервер, написанный вручную (на базе |
Ноль зависимостей | Чистый C#; разбор и сериализация JSON — встроенная реализация; нет зависимостей от сторонних Unity-пакетов или внешних сред выполнения. |
Совместимость | Unity 2022.3 (.NET Standard 2.1 / C# 9) и Unity 6; только для редактора, не влияет на рантайм-сборку. |
Аннотация типов инструментов | Каждый инструмент помечен как |
Контроль прав доступа | На панели конфигурации можно переключать режим только чтение / чтение-запись; в режиме только чтения сервер напрямую отклоняет все инструменты записи (возвращается |
Безопасность основного потока | Все вызовы Unity API выполняются через диспетчер основного потока; HTTP-рабочие потоки никогда не обращаются к Unity API напрямую. |
Отсутствие зависимостей на этапе компиляции для VRChat | Чтение и запись для VRCSDK3 / Modular Avatar / VRCFury выполняются только через |
Журнал в реальном времени | В панели конфигурации есть окно журнала в реальном времени (подключения / вызовы / отказы / ошибки, с цветовым разделением), также пересылаются сообщения консоли Unity. |
Расширяемость | Три способа расширения: аннотация атрибутом ( |
Скопируйте этот репозиторий в любое место (например, в ../vrchat-project-mcp рядом с проектом);
В проекте Unity откройте Window → Package Manager → + → Add package from disk… и выберите package.json в этом каталоге;
Либо добавьте запись прямо в Packages/manifest.json проекта:
{
"dependencies": {
"com.vrchat-project.mcp": "file:../../vrchat-project-mcp"
}
}Скопируйте всю папку в Assets/ проекта (например, Assets/vrchat-project-mcp/). Unity скомпилирует её автоматически. package.json можно оставить или удалить.
После публикации репозитория в Git-сервисе выберите в Package Manager Add package from git URL… и укажите адрес репозитория.
После установки в строке меню появляется пункт Tools → VRChat Project MCP (панель конфигурации / запуск сервера / остановка сервера).
Откройте Tools → VRChat Project MCP → Панель конфигурации;
Убедитесь, что адрес прослушивания по умолчанию 127.0.0.1:8765 и права доступа (по умолчанию чтение-запись) заданы верно;
Нажмите Запустить сервер (если включена опция «Автозапуск сервера после запуска редактора», сервер уже запущен);
Откройте в браузере http://127.0.0.1:8765/ — вы увидите информационную страницу на китайском языке, а GET /health возвращает статус в JSON;
Пусть ваш агент выполняет вызовы по HTTP (примеры — в Примерах подключения клиента):
POST http://127.0.0.1:8765/mcp
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"my-agent","version":"1.0"}}}Затем используйте tools/list, чтобы увидеть все инструменты, и tools/call для их вызова. Агент может сначала вызвать mcp.get_status, чтобы узнать режим работы сервера и список инструментов, воспользоваться unity.get_console_logs для поиска ошибок и vrc.get_avatar_info, чтобы получить отчёт об аватаре.
Tools → VRChat Project MCP → Панель конфигурации:
Параметр | Описание |
Адрес прослушивания | По умолчанию |
Порт | По умолчанию |
Права доступа | Только чтение (отклонять все инструменты записи) / Чтение-запись (разрешить запросы и запись). Изменение вступает в силу немедленно, сервер блокирует в реальном времени. |
Автозапуск | Автоматически запускать сервер после запуска редактора. |
Окно журнала в реальном времени | В реальном времени выводит события подключения, вызовов, отказов и ошибок; поддерживаются автопрокрутка и очистка. |
Быстрые действия | Запуск / Остановка / Перезапуск / Копировать MCP-эндпоинт / Очистить журнал. |
Изменения адреса прослушивания и порта вступают в силу только после нажатия «Перезапуск»; изменение режима прав применяется немедленно. Все настройки хранятся в EditorPrefs отдельно для каждого проекта.
Эндпоинт | Метод | Описание |
| POST | Streamable HTTP (MCP 2025-03-26): JSON-запрос → JSON-ответ; если заголовок |
| DELETE | Завершение сеанса (сервис не хранит состояние, сразу возвращается 200). |
| GET | Классический HTTP+SSE (MCP 2024-11-05): устанавливается длительное соединение и отправляется событие |
| POST | Канал клиент → сервер для классической SSE-передачи; возвращается 202, результат отправляется обратно через SSE-событие. |
| GET | JSON для проверки работоспособности (состояние / режим / количество инструментов / список эндпоинтов). |
| GET | Информационная страница на китайском языке. |
Протокол: MCP поверх JSON-RPC 2.0, последовательность initialize → notifications/initialized → tools/list → tools/call;
Поддерживаются пакетные запросы в виде массива; протокол совместим с версиями 2024-11-05 / 2025-03-26 / 2025-06-18 (возвращается версия клиента);
Все ответы содержат CORS-заголовки (Access-Control-Allow-Origin: * и др.), поэтому браузерные клиенты (например, MCP Inspector) могут обращаться к серверу напрямую.
Колонка «Тип»:
Запрос— безопасно, только чтение;Запись— изменяет сцену/ассеты/проект, в режиме только чтения отклоняется сервером; перед вызовом агенту рекомендуется запросить у пользователя повторное подтверждение.
Инструмент | Тип | Описание |
| Запрос | Состояние работы сервера, режим доступа, полный список инструментов (с пометками чтения/записи) и эндпоинты. |
| Запрос | Повторно сканирует сборки и обновляет реестр инструментов (вызывается после добавления или удаления расширений). |
Инструмент | Тип | Описание |
| Запрос | Основная информация о проекте (название продукта / версия Unity / платформа / сцены сборки / статистика ассетов). |
| Запрос | Список установленных UPM-пакетов (включая определение пакетов, связанных с VRChat). |
| Запрос | Память процесса / управляемая память / статистика объектов и компонентов сцены / количество ассетов по типам / текущее выделение в редакторе. |
| Запрос | Журнал консоли (кольцевой буфер в памяти + хвост файла Editor.log), с фильтрацией по уровню / ключевым словам. |
| Запрос | Информация об активной сцене (имя / путь / статистика объектов / корневые объекты / топ компонентов). |
| Запрос | Список объектов сцены (включая неактивные) с фильтром по имени / ключевым словам компонентов. |
| Запрос | Полная информация об объекте (положение/поворот / список компонентов / сериализованные поля каждого компонента). |
| Запрос | Текущие выделенные объекты в редакторе. |
| Запись | Установить выделение (путь к ассету / #ID экземпляра / путь в сцене). |
| Запись | Универсальная установка сериализованного поля (объекты сцены и ассеты-префабы, автосохранение); поддерживается путь |
| Запись | Установить положение объекта (позиция / углы Эйлера / масштаб). |
| Запись | Создать GameObject (можно указать родительский объект и начальные компоненты). |
| Запись | Уничтожить объект сцены (для ассетов-префабов по умолчанию отказ). |
| Запись | Сохранить префаб из объекта сцены. |
| Запись | Создать экземпляр префаба в сцене. |
| Запись | Открыть сцену (можно предварительно сохранить текущую). |
| Запись | Сохранить текущую сцену. |
| Запись | Выполнить пункт меню редактора (например, |
| Запрос | Поиск и вывод списка ассетов (фильтр по типу / папке / ключевым словам). |
| Запрос | Детали ассета (тип / размер / зависимости / импортёр / сводка префаба). |
| Запрос | Чтение текстовых файлов внутри проекта (только в Assets/, Packages/, ProjectSettings/). |
| Запись | Создание ассета (AnimatorController/Material/PhysicMaterial/AnimationClip/любой ScriptableObject). |
| Запись | Создание файла C#-скрипта (шаблон MonoBehaviour, опциональное пространство имён). |
| Запись | Копирование ассета (при совпадении имени автоматически добавляется номер). |
| Запись | Удаление ассета (по умолчанию перемещается в корзину). |
| Запись | Создание папки в Assets (последовательно, по уровням). |
| Запись | Сохранить и обновить базу данных ассетов. |
工具 | 类型 | 说明 |
| 查询 | 列出场景与预制件中的头像（VRCAvatarDescriptor / 旧版描述符） |
| 查询 | 头像完整详情：描述符字段/动画层/表情菜单树/表情参数/性能统计/渲染骨骼统计/MA·VRCFury 等插件组件 —— 供 Agent 输出报告与建议 |
| 查询 | 性能统计（面数/骨骼/材质/PhysBone/碰撞体计数与等级；优先 SDK 官方计算，否则按官方阈值估算并标注） |
| 查询 | VRChat 相关 SDK/插件版本探测（VRCSDK/MA/VRCFury/Poiyomi/DynamicBone/AAO 等） |
| 查询 | 指定组件（MA/VRCFury/PhysBone 等）完整序列化参数 |
| 写入 | 修改任意组件（MA/VRCFury 等）序列化字段（枚举用名称，资源引用用资产路径） |
| 查询 | 列出项目中的表情菜单（VRCExpressionsMenu）资产 |
| 查询 | 读取菜单结构（控件类型/参数/值/图标/子菜单/标签，支持递归） |
| 写入 | 新建表情菜单资产 |
| 写入 | 复制表情菜单资产 |
| 写入 | 新增/修改/删除菜单控件（Button/Toggle/SubMenu/TwoAxisPuppet/FourAxisPuppet/RadialPuppet，含 labels 与 subParameters） |
| 写入 | 把菜单/参数资产绑定到头像描述符（场景对象与预制件均支持） |
| 查询 | 列出项目中的表情参数（VRCExpressionParameters）资产 |
| 查询 | 读取参数列表（名称/类型 Int·Float·Bool/默认值/是否保存） |
| 写入 | 新建表情参数资产 |
| 写入 | 复制表情参数资产 |
| 写入 | 新增/修改/删除表情参数 |
| 查询 | 读取 ModularAvatarParameters 组件全部参数 |
| 写入 | 新增/修改/删除 MA 参数（sync 按名称设置，非法值会列出该版本可选值） |
工具 | 类型 | 说明 |
| 查询 | 扩展示例（演示自定义工具注册，可删除 |
// 读取头像报告
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
"name":"vrc.get_avatar_info",
"arguments":{"target":"Assets/MyAvatar.prefab","includeStats":true}}}
// 改 MA 参数默认值（写入，只读模式会被拒绝）
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
"name":"vrc.set_component_property",
"arguments":{"target":"Assets/MyAvatar.prefab","componentType":"ModularAvatarParameters",
"propertyPath":"parameters.Array.data[0].defaultValue","value":1.0}}}
// 给表情菜单加一个开关
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
"name":"vrc.set_menu_control",
"arguments":{"menuPath":"Assets/Menus/Main.asset","action":"add",
"control":{"name":"开关","type":"Toggle","parameter":"MyParam"}}}}
// 排查控制台报错
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{
"name":"unity.get_console_logs",
"arguments":{"level":"Error","maxLines":50}}}服务端在执行 任何 写入类工具前检查当前访问模式；只读模式下直接返回 isError 结果：
{
"content": [{"type":"text","text":"当前为【只读】模式，已拒绝写入类工具调用「vrc.set_parameter」。…"}],
"isError": true,
"structuredContent": {"error": {"code":"permission_denied","access":"write","mode":"readonly"}}
}Agent 端建议策略：调用 tools/list 或 mcp.get_status 获取每个工具的 _meta.access；对 write 类型工具先向用户确认，且无需在客户端重复实现拦截（服务端已兜底）。
# 握手
curl -s http://127.0.0.1:8765/mcp -H "Content-Type: application/json" -d \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"curl","version":"1"}}}'
# 工具清单（注意每个工具 description 前缀的【查询】/【写入】与 _meta.access）
curl -s http://127.0.0.1:8765/mcp -H "Content-Type: application/json" -d \
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
# 调用工具
curl -s http://127.0.0.1:8765/mcp -H "Content-Type: application/json" -d \
'{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"mcp.get_status"}}'# Accept 带 text/event-stream 时响应为 SSE 事件流
curl -sN http://127.0.0.1:8765/mcp -H "Accept: text/event-stream" \
-H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'打开 MCP Inspector，Transport 选 Streamable HTTP，URL 填 http://127.0.0.1:8765/mcp（本服务已内置 CORS 支持）。
用社区桥接工具把 HTTP MCP 转成 stdio（桥接工具运行在客户端侧，不影响本插件零依赖）：
npx mcp-remote http://127.0.0.1:8765/sse或使用自研 Agent 直接以 HTTP 调用（POST /mcp，参考上文 JSON-RPC 流程）。
插件预留了三层扩展点，无需修改插件源码即可新增能力：
[McpTool] 属性标注（推荐）在任意引用了 VrchatProjectMcp.Core 程序集的代码中定义公开静态方法并标注特性，插件启动或调用 mcp.refresh_tools 时自动扫描注册：
using VrchatProjectMcp.Core.Json;
using VrchatProjectMcp.Core.Mcp;
public static class MyTools
{
// access 必须标明：Query（查询）或 Write（写入，只读模式会被服务端拒绝）
[McpTool("mytools.check_avatar", McpToolAccess.Query, "mytools", "检查头像…")]
public static object Check([McpParam("头像路径")] string path = null)
{
return new JsonObject().Set("ok", true);
}
}IMcpToolProvider 接口适合动态决定工具集合的场景（如"检测到某插件安装后才注册对应工具"）：
public sealed class MyProvider : IMcpToolProvider
{
public IEnumerable<McpToolDefinition> RegisterTools()
{
var def = new McpToolDefinition
{
Name = "mytools.dynamic",
Access = McpToolAccess.Write,
Category = "mytools",
Description = "动态注册示例",
};
def.Parameters.Add(new McpParamDefinition { Name = "x", JsonType = "string", Required = true });
def.Handler = args => new JsonObject().Set("done", true);
yield return def;
}
}完整可运行示例见 Editor/Tools/Examples/ExampleExtensionTools.cs。
// 运行时注册工具
McpToolRegistry.Instance.RegisterTool(myDefinition);
// 注册 MCP 资源（resources/list 可见，Agent 可 resources/read）
McpToolRegistry.Instance.Resources.Add(new McpResourceDefinition
{
Uri = "mcp://my-report",
Name = "我的报告",
ReadHandler = () => new JsonObject().Set("data", 123),
});
// 自定义 HTTP 端点（需服务已启动）
McpServerController.Server?.AddHandler("GET", "/my-endpoint", ctx =>
{
// ctx.BodyText 读取请求体；用 McpServerController.Server.WriteResponse(...) 写响应
});扫描范围：只扫描"引用了 VrchatProjectMcp.Core 程序集"的程序集，不会遍历 Unity 全部类型，开销可控。
项 | 说明 |
Unity 版本 | 2022.3（.NET Standard 2.1 / C# 9）与 Unity 6（全部代码按 C# 9 语法编写，并在本地用 LangVersion 9.0 编译验证） |
平台 | Windows / macOS / Linux 编辑器（HTTP 服务器使用 |
播放模式 | 服务在播放模式同样可用；但播放模式中对场景的写入会在退出播放模式后丢失，请谨慎 |
编译依赖 | 对 VRCSDK3 / MA / VRCFury 零编译期依赖；未安装时相关工具返回明确错误（不影响插件本身使用） |
性能统计 | 优先反射调用 SDK |
菜单/参数资产创建与编辑 | 需要项目安装 VRChat SDK3（这些资产类型由 SDK 定义）；SDK2 旧头像仅支持信息读取 |
预制件扫描 |
|
弹窗类操作 | 工具执行带 120 秒主线程超时；涉及模态弹窗的操作可能超时（插件已避免在工具内弹窗） |
长驻资源 | SSE 长连接按需建立；域重载前服务自动停止并清理，防止残留端口占用 |
默认只监听 127.0.0.1：仅本机进程可访问。改为 0.0.0.0 会把服务暴露给局域网内所有设备，请务必了解风险；
本插件当前不内置鉴权（MCP 社区标准做法是由客户端侧代理统一鉴权）。如暴露到公网，请在反向代理层加认证；
只读模式是最后一道保险，但仍建议 Agent 对写入类操作先获得用户确认；
unity.read_text_asset 仅允许读取 Assets/、Packages/、ProjectSettings/ 下的文件，无法越界读系统文件。
vrchat-project-mcp/
├── package.json # UPM 包清单（unity ≥ 2022.3，零依赖）
├── README.md # 本文档
├── LICENSE # MIT
├── Runtime/ # 纯 C# 协议层（noEngineReferences，无 Unity 依赖）
│ ├── VrchatProjectMcp.Core.asmdef
│ ├── Mcp/
│ │ ├── Json/MiniJson.cs # 内置 JSON 解析/序列化（零依赖）
│ │ ├── McpTypes.cs # 模式枚举/权限接口/资源定义/扩展接口
│ │ ├── McpToolAttribute.cs # [McpTool]/[McpParam] 特性（扩展方式二）
│ │ ├── McpToolDefinition.cs # 工具定义 + inputSchema 生成 + 参数绑定
│ │ ├── McpToolRegistry.cs # 扫描/注册/权限门控/调用执行
│ │ ├── JsonRpcCore.cs # JSON-RPC 2.0 分发（initialize/tools/resources）
│ │ └── IMcpLogger.cs # 日志接口（宿主实现）
│ └── Net/
│ ├── SimpleHttpServer.cs # TcpListener 手写 HTTP/1.1 服务器（SSE/CORS/chunked）
│ └── McpHttpEndpoints.cs # /mcp /sse /message /health / 端点
├── Editor/ # Unity 编辑器层
│ ├── VrchatProjectMcp.Editor.asmdef
│ ├── Core/
│ │ ├── McpMainThreadDispatcher.cs # 主线程调度（HTTP 线程 → Unity 主线程）
│ │ └── McpServerController.cs # 生命周期控制/组装/内置资源/菜单项
│ ├── Settings/
│ │ ├── McpSettings.cs # 配置（EditorPrefs 持久化，按项目隔离）
│ │ └── McpSettingsWindow.cs # 配置面板（地址/端口/权限/实时日志）
│ ├── Logging/
│ │ ├── McpEditorLogger.cs # 日志器（窗口富文本 + Unity 控制台）
│ │ └── McpConsoleCapture.cs # 控制台日志环形缓冲采集
│ └── Tools/
│ ├── ToolHelpers.cs # 目标解析/序列化读写/预制件编辑等公共辅助
│ ├── McpMetaTools.cs # mcp.* 元工具
│ ├── UnityProjectTools.cs # unity.* 项目/包/资源/日志
│ ├── UnitySceneTools.cs # unity.* 场景/对象/组件/预制件
│ ├── UnityAssetTools.cs # unity.* 资产
│ ├── Vrc/
│ │ ├── VrcReflection.cs # VRChat SDK 类型反射（无编译期依赖）
│ │ ├── VrcCoreTools.cs # vrc.* 头像/性能/插件探测/组件读写
│ │ ├── VrcMenuTools.cs # vrc.* 表情菜单 新建/复制/编辑/绑定
│ │ ├── VrcParameterTools.cs # vrc.* 表情参数 新建/复制/编辑
│ │ └── VrcMaTools.cs # vrc.ma_* MA 参数
│ └── Examples/
│ └── ExampleExtensionTools.cs# 扩展示例（可删除）
└── DevTests~/ # 开发期冒烟测试（目录名带 ~ 后缀，Unity 不会导入，非包内容）
└── CoreSanity/ # Core 协议层 37 项端到端测试（dotnet 工程）
DevTests~使用 UPM 约定的~后缀命名，Unity 导入包时会完全忽略该目录；如需本地运行测试：dotnet run --project DevTests~/CoreSanity/CoreSanity.csproj。
问：为什么不用 HttpListener / WebSocket？
Unity 2022/Unity 6 的 .NET Standard 2.1 API 级别下 HttpListener 不可用；WebSocket 需要第三方库。TcpListener + 手写 HTTP/1.1 是零依赖且跨版本最稳的方案。
问：插件会打进游戏包里吗？
不会。核心逻辑在 Editor 程序集（includePlatforms: ["Editor"]），协议层虽在 Runtime 目录但仅被 Editor 引用，构建时不会进入玩家。
问：只读模式下为什么还要标注工具类型？ 类型标注服务于 Agent 决策（是否二次确认、是否尝试调用），服务端拦截是兜底保险，两者叠加更安全。
问：没装 VRChat SDK 能用吗？ 能。Unity 常规工具全部可用；VRChat 工具中「头像信息/组件读写/插件探测」尽力可用（按类型名反射），「菜单/参数资产创建与编辑」会返回明确提示。
问：如何排查 Agent 调用失败？
看配置面板实时日志框（每次连接与调用都会打印），或让 Agent 调用 unity.get_console_logs 读取控制台与 Editor.log。
问：端口被占用怎么办？
配置面板改端口后点「重启」；或填端口 0 自动分配（实际端口显示在状态栏）。
0.1.0（初始版本）：HTTP(JSON/SSE) MCP 服务、27 个 Unity 常规工具、19 个 VRChat 专用工具、2 个元工具、1 个扩展示例；只读/读写权限门控；配置面板与实时日志；扩展点；中文注释与文档。
MIT（见 LICENSE）。
This server cannot be deployed
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP registry & directory: search, find & install 31k+ MCP servers & tools. Catalog and marketplace.
A paid remote MCP for Unity-MCP, built to return verdicts, receipts, usage logs, and audit-ready JSO
Generate, edit, and deploy immersive 3D/WebGL web projects from any MCP assistant.
