VRChat Project MCP
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 "Install 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 MCPcheck 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.
VRChat Project MCP
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_editorcapabilities 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).
Table of Contents
Related MCP server: unityxclaude
Core Features
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 ( |
Installation
Method 1: UPM Local Package (Recommended)
Copy this repository to any location (e.g.,
../vrchat-project-mcpnext to your project);In the Unity project, open
Window → Package Manager → + → Add package from disk…and select thepackage.jsonin this directory;Or directly append to the project's
Packages/manifest.json:
{
"dependencies": {
"com.vrchat-project.mcp": "file:../../vrchat-project-mcp"
}
}Method 2: Place Directly in Assets
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.
Method 3: Git URL (UPM)
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).
Quick Start
Open Tools → VRChat Project MCP → Configuration Panel;
Confirm the default listen address
127.0.0.1:8765and 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 /healthreturns 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.
Configuration Panel
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.
HTTP Endpoints and Protocol
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.
Tool List
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.
MCP Meta Tools (mcp)
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) |
Unity General (unity)
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 |
VRChat-Specific (vrc)
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) |
Extension example (example)
Tool | Type | Description |
| Query | Extension example (demonstrates custom tool registration; |
Common invocation examples
// 读取头像报告
{"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}}}Read-only / read-write permission modes
The server checks the current access mode before executing any write-type tool; in read-only mode it directly returns an
isErrorresult:
{
"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/listormcp.get_statusto get each tool's_meta.access; confirm with the user beforewrite-type tools, and there is no need to re-implement interception on the client side (the server already provides a fallback).
Client integration examples
curl (JSON mode)
# 握手
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"}}'curl (SSE mode)
# 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 (browser)
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).
Claude Desktop / other stdio-only clients
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).
Extension guide
The plugin reserves three layers of extension points, so new capabilities can be added without modifying the plugin source code:
Method 1: [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);
}
}Method 2: IMcpToolProvider interface
Suitable 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.
Method 3: Runtime registration / custom resources / custom HTTP endpoints
// 运行时注册工具
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.
Compatibility and known limitations
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 |
Security notes
By default it only listens on
127.0.0.1: only local processes can access it. Changing it to0.0.0.0exposes 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_assetonly allows reading files underAssets/,Packages/, andProjectSettings/; it cannot read system files outside those paths.
Project structure
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.
FAQ
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).
Version history
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.
License
MIT (see LICENSE).
This server cannot be installed
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides 20 tools to control the Unity Editor with natural language, including scene management, component manipulation, script generation, asset handling, project settings, builds, and live C# execution.2MIT
- AlicenseNot gradedqualityCmaintenanceA local MCP server for Unity Editor that provides 20 editor tools to control scripts, scenes, components, assets, and builds.2MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server for Unity that enables AI agents to query and control the Unity Editor, providing tools for scene management, object manipulation, and asset browsing.MIT
- AlicenseNot gradedqualityAmaintenanceMCP server for safely inspecting and editing Unity/VRChat prefabs, scenes, and assets. It diagnoses override collisions, broken references, and runtime exceptions, with read-only YAML analysis and write operations via an Editor Bridge.11MIT
Related MCP Connectors
Markdown-first MCP server for Notion API with 8 composite tools and 39 actions.
Generate, edit, and deploy immersive 3D/WebGL web projects from any MCP assistant.
A MCP server built for developers enabling Git based project management with project and personal…
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/dpwgc/vrchat-project-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server