Provides tools for managing Unity projects, including scene and GameObject inspection/editing, asset management, console log queries, and editor operations within the Unity Editor.
Provides tools for managing VRChat avatars, including avatar details, performance stats, expression menus and parameters, and editing Modular Avatar/VRCFury components.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@VRChat Project MCP check my avatar's performance stats"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Unity Editor MCP (Model Context Protocol) plugin for VRChat avatar development.
It exposes 49 tools to external AI agents through a built-in HTTP service (JSON-RPC 2.0 / SSE), covering:
General Unity project capabilities: project info, scene/object/component query and editing, asset management, console log troubleshooting (aligned with the manage_scene / manage_gameobject / manage_asset / manage_editor capabilities of existing unity-mcp-style plugins);
VRChat-specific capabilities: avatar detail reports (menus/parameters/bindings/performance/resource usage/installed plugins), editing MA / VRCFury component parameters, creating/duplicating/editing/binding expression menus and expression parameter files.
Pure C# implementation with zero third-party dependencies (no Python / JS / Newtonsoft.Json or any other libraries), compatible with Unity 2022.3 and Unity 6 (Windows / macOS / Linux Editor).
Related MCP server: unityxclaude
Feature | Description |
HTTP port service | Built-in hand-written HTTP/1.1 server (based on |
Zero dependencies | Pure C#; JSON parsing/serialization is a built-in implementation; no third-party Unity packages or external runtimes required |
Compatibility | Unity 2022.3 (.NET Standard 2.1 / C# 9) and Unity 6; editor-only, does not affect runtime builds |
Tool type annotation | Each tool is annotated as |
Permission gating | The configuration panel can switch between read-only / read-write modes; in read-only mode the server directly rejects all write-type tools (returns |
Main-thread safety | All Unity API calls go through a main-thread dispatcher; HTTP worker threads never touch Unity APIs directly |
No compile-time VRChat dependency | All reads/writes to VRCSDK3 / Modular Avatar / VRCFury go through |
Real-time logging | The configuration panel includes a built-in real-time log box (connection/call/rejection/error events, color-coded), and also forwards Unity console output |
Extensible | Three extension methods: attribute annotation ( |
Copy this repository to any location (e.g., ../vrchat-project-mcp next to your project);
In the Unity project, open Window → Package Manager → + → Add package from disk… and select the package.json in this directory;
Or directly append to the project's Packages/manifest.json:
{
"dependencies": {
"com.vrchat-project.mcp": "file:../../vrchat-project-mcp"
}
}Copy the entire folder into the project's Assets/ directory (e.g., Assets/vrchat-project-mcp/), and Unity will compile it automatically. The package.json can be kept or deleted.
After pushing the repository to a Git service, select Add package from git URL… in the Package Manager and enter the repository URL.
After installation, the menu bar shows Tools → VRChat Project MCP (configuration panel / start server / stop server).
Open Tools → VRChat Project MCP → Configuration Panel;
Confirm the default listen address 127.0.0.1:8765 and operation permission (read-write by default);
Click Start Server (if "auto-start server after editor launch" is enabled, it will already be running);
Open http://127.0.0.1:8765/ in a browser to see the Chinese info page; GET /health returns a JSON status;
Have your agent call via HTTP (see examples in Client Integration Examples):
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"}}}Then use tools/list to view all tools and tools/call to execute them. The agent can first call mcp.get_status to understand the service mode and tool list, use unity.get_console_logs to troubleshoot errors, and use vrc.get_avatar_info to output an avatar report.
Tools → VRChat Project MCP → Configuration Panel:
Configuration Item | Description |
Listen address | Default |
Port | Default |
Operation permission | Read-only (rejects all write-type tools) / Read-write (allows queries and writes). Changes take effect immediately, intercepted in real time by the server |
Auto-start | Automatically start the service after the editor launches |
Real-time log box | Prints connection, call, rejection, and error events in real time, with auto-scroll and clear support |
Quick actions | Start / Stop / Restart / Copy MCP endpoint / Clear logs |
Changes to the listen address and port require clicking "Restart" to take effect; permission mode changes take effect immediately. All configuration is saved per-project in EditorPrefs.
Endpoint | Method | Description |
| POST | Streamable HTTP (MCP 2025-03-26): JSON request → JSON response; if the request header |
| DELETE | Session end (this service is stateless, returns 200 directly) |
| GET | Legacy HTTP+SSE (MCP 2024-11-05): establishes a long-lived connection and sends an |
| POST | Client→server channel for the legacy SSE transport; returns 202, results are written back via SSE events |
| GET | Health check JSON (status/mode/tool count/endpoint list) |
| GET | Chinese info page |
Protocol: MCP over JSON-RPC 2.0, flow initialize → notifications/initialized → tools/list → tools/call;
Supports batch array requests; protocol versions compatible with 2024-11-05 / 2025-03-26 / 2025-06-18 (echoes the client version);
All responses include CORS headers (Access-Control-Allow-Origin: *, etc.), so browser clients (such as MCP Inspector) can access directly.
Type column:
Query= read-only safe;Write= modifies scenes/assets/projects, rejected by the server in read-only mode, and agents are advised to confirm with the user before calling.
Tool | Type | Description |
| Query | Service running status, access mode, full tool list (with read/write annotations) and endpoints |
| Query | Re-scan assemblies and refresh the tool registry (call after adding/removing extensions) |
Tool | Type | Description |
| Query | Basic project info (product name/Unity version/platform/build scenes/asset statistics) |
| Query | Installed UPM package list (including VRChat-related package detection) |
| Query | Process memory/managed memory/scene object component statistics/asset counts by type/current selection |
| Query | Console logs (in-memory ring buffer + tail of Editor.log file), supports level/keyword filtering |
| Query | Active scene info (name/path/object statistics/root objects/component Top statistics) |
| Query | List scene objects filtered by name/component keywords (including inactive ones) |
| Query | Complete object info (transform/component list/serialized fields of each component) |
| Query | Currently selected objects in the editor |
| Write | Set selection (asset path / #instance ID / scene path) |
| Write | Generic serialized field setting (scene objects and prefab assets, auto-save), supports |
| Write | Set object transform (position/euler rotation/scale) |
| Write | Create a GameObject (can specify parent and initial components) |
| Write | Destroy scene objects (prefab assets rejected by default) |
| Write | Save a prefab from a scene object |
| Write | Instantiate a prefab into the scene |
| Write | Open a scene (optionally save the current scene first) |
| Write | Save the current scene |
| Write | Execute an editor menu item (e.g., |
| Query | Search and list assets (type/folder/keyword filters) |
| Query | Asset details (type/size/dependencies/importer/prefab summary) |
| Query | Read text files in the project (limited to Assets/, Packages/, ProjectSettings/) |
| Write | Create assets (AnimatorController/Material/PhysicMaterial/AnimationClip/any ScriptableObject) |
| Write | Create a C# script file (MonoBehaviour template, optional namespace) |
| Write | Copy assets (auto-appends a number on name conflicts) |
| Write | Delete assets (moves to recycle bin by default) |
| Write | Create folders under Assets (level by level) |
| Write | Save and refresh the asset database |
Tool | Type | Description |
| Query | List avatars in the scene and project prefabs (VRCAvatarDescriptor / legacy descriptors) |
| Query | Full avatar details: descriptor fields/animation layers/expression menu tree/expression parameters/performance stats/render bone stats/plugin components such as MA·VRCFury — for the Agent to output reports and suggestions |
| Query | Performance stats (poly count/bones/materials/PhysBone/collider counts and ranks; prefers the SDK's official calculation, otherwise estimates by official thresholds and marks it as estimated) |
| Query | Detect versions of VRChat-related SDKs/plugins (VRCSDK/MA/VRCFury/Poiyomi/DynamicBone/AAO, etc.) |
| Query | Full serialized parameters of a specified component (MA/VRCFury/PhysBone, etc.) |
| Write | Modify serialized fields of any component (MA/VRCFury, etc.) (enums by name, asset references by asset path) |
| Query | List expression menu (VRCExpressionsMenu) assets in the project |
| Query | Read the menu structure (control type/parameter/value/icon/submenu/label, with recursion support) |
| Write | Create a new expression menu asset |
| Write | Copy an expression menu asset |
| Write | Add/modify/delete menu controls (Button/Toggle/SubMenu/TwoAxisPuppet/FourAxisPuppet/RadialPuppet, including labels and subParameters) |
| Write | Bind menu/parameter assets to the avatar descriptor (supports both scene objects and prefabs) |
| Query | List expression parameter (VRCExpressionParameters) assets in the project |
| Query | Read the parameter list (name/type Int·Float·Bool/default value/whether saved) |
| Write | Create a new expression parameter asset |
| Write | Copy an expression parameter asset |
| Write | Add/modify/delete expression parameters |
| Query | Read all parameters of the ModularAvatarParameters component |
| Write | Add/modify/delete MA parameters (syncType is set by name; invalid values will list the valid options for that version) |
Tool | Type | Description |
| Query | Extension example (demonstrates custom tool registration; |
// 读取头像报告
{"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}}}The server checks the current access mode before executing any write-type tool; in read-only mode it directly returns an isError result:
{
"content": [{"type":"text","text":"当前为【只读】模式，已拒绝写入类工具调用「vrc.set_parameter」。…"}],
"isError": true,
"structuredContent": {"error": {"code":"permission_denied","access":"write","mode":"readonly"}}
}Recommended strategy on the Agent side: call tools/list or mcp.get_status to get each tool's _meta.access; confirm with the user before write-type tools, and there is no need to re-implement interception on the client side (the server already provides a fallback).
# 握手
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"}'Open MCP Inspector, select Streamable HTTP as the Transport, and enter http://127.0.0.1:8765/mcp as the URL (this service has built-in CORS support).
Use a community bridge tool to convert HTTP MCP to stdio (the bridge runs on the client side and does not affect this plugin's zero dependencies):
npx mcp-remote http://127.0.0.1:8765/sseOr use a custom Agent to call directly over HTTP (POST /mcp, see the JSON-RPC flow above).
The plugin reserves three layers of extension points, so new capabilities can be added without modifying the plugin source code:
[McpTool] attribute annotation (recommended)Define public static methods in any code that references the VrchatProjectMcp.Core assembly and annotate them with the attribute; they are automatically scanned and registered when the plugin starts or when mcp.refresh_tools is called:
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 interfaceSuitable for scenarios where the tool set is determined dynamically (e.g., "register the corresponding tool only after detecting that a certain plugin is installed"):
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;
}
}See Editor/Tools/Examples/ExampleExtensionTools.cs for a complete runnable example.
// 运行时注册工具
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(...) 写响应
});Scan scope: only assemblies that "reference the VrchatProjectMcp.Core assembly" are scanned; it does not iterate over all Unity types, so the overhead is manageable.
Item | Description |
Unity version | 2022.3 (.NET Standard 2.1 / C# 9) and Unity 6 (all code is written in C# 9 syntax and verified locally by compiling with LangVersion 9.0) |
Platform | Windows / macOS / Linux editor (the HTTP server uses |
Play mode | The service also works in play mode; however, writes to the scene in play mode are lost after exiting play mode, so proceed with caution |
Compile dependencies | Zero compile-time dependencies on VRCSDK3 / MA / VRCFury; when they are not installed, the related tools return a clear error (without affecting the plugin itself) |
Performance stats | Prefers reflecting into the SDK's |
Menu/parameter asset creation and editing | Requires the VRChat SDK3 to be installed in the project (these asset types are defined by the SDK); SDK2 legacy avatars only support reading information |
Prefab scanning |
|
Modal dialog operations | Tool execution has a 120-second main-thread timeout; operations involving modal dialogs may time out (the plugin avoids showing dialogs inside tools) |
Long-lived resources | SSE long connections are established on demand; before domain reload the service automatically stops and cleans up to prevent lingering port usage |
By default it only listens on 127.0.0.1: only local processes can access it. Changing it to 0.0.0.0 exposes the service to all devices on the LAN; please be sure you understand the risks;
This plugin currently has no built-in authentication (the MCP community standard is to have the client-side proxy handle authentication centrally). If exposed to the public internet, add authentication at the reverse proxy layer;
Read-only mode is the last line of defense, but it is still recommended that the Agent obtain user confirmation before write-type operations;
unity.read_text_asset only allows reading files under Assets/, Packages/, and ProjectSettings/; it cannot read system files outside those paths.
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~uses the~suffix convention from UPM, so Unity completely ignores this directory when importing the package; to run tests locally:dotnet run --project DevTests~/CoreSanity/CoreSanity.csproj.
Q: Why not use HttpListener / WebSocket?
At the .NET Standard 2.1 API level of Unity 2022/Unity 6, HttpListener is unavailable; WebSocket requires a third-party library. TcpListener + hand-written HTTP/1.1 is the most stable zero-dependency, cross-version solution.
Q: Will the plugin be included in the game build?
No. The core logic is in the Editor assembly (includePlatforms: ["Editor"]); although the protocol layer is in the Runtime directory, it is only referenced by the Editor and will not enter the player at build time.
Q: Why still annotate tool types in read-only mode?
The type annotation serves the Agent's decision-making (whether to double-confirm, whether to attempt the call); server-side interception is a fallback safeguard, and combining both is safer.
Q: Can it be used without the VRChat SDK installed?
Yes. All regular Unity tools work; among the VRChat tools, "avatar info/component read-write/plugin detection" work on a best-effort basis (via reflection by type name), while "menu/parameter asset creation and editing" returns a clear message.
Q: How do I troubleshoot failed Agent calls?
Check the real-time log box in the configuration panel (every connection and call is printed), or have the Agent call unity.get_console_logs to read the console and Editor.log.
Q: What if the port is already in use?
Change the port in the configuration panel and click "Restart"; or enter port 0 for automatic assignment (the actual port is shown in the status bar).
0.1.0 (initial version): HTTP (JSON/SSE) MCP service, 27 regular Unity tools, 19 VRChat-specific tools, 2 meta tools, 1 extension example; read-only/read-write permission gating; configuration panel and real-time logs; extension points; Chinese comments and documentation.
MIT (see LICENSE).
This server cannot be deployed
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
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.
The OpenRouter MCP server plugs OpenRouter into the AI tools you already use. Once connected, your assistant can pull live OpenRouter data (models, prices, your credits, rankings, and docs) and send quick test messages, all without leaving your editor.
