vrc-mcp-proxy
The vrc-mcp-proxy server lets you remotely control and automate the Unity Editor via MCP, acting as a correcting/safety proxy over the upstream MCP-for-Unity server. Key capabilities include:
Execute C# Code: Run arbitrary C# code inside the Unity Editor, with compiler options, execution history, safety checks (blocks unsafe
usingdirectives), and idempotency guards.Manage Assets: Full CRUD on Unity assets — import, create, modify, delete, duplicate, move, rename, search, and organize folders.
Manage GameObjects: Create, modify, delete, duplicate, and reposition GameObjects, including prefab instantiation and look-at operations.
Find GameObjects: Search the scene by name, tag, layer, component type, path, or ID with pagination.
Manage Scenes: Create, load, save, close, query hierarchy, set active scene, and validate scenes.
Manage Editor: Control playback (play/pause/stop), set active tools, manage tags/layers, deploy/restore packages, and perform undo/redo.
Manage Cameras: Create and configure cameras (including Cinemachine), capture screenshots (single, surround, orbit), and control blending/targeting.
Manage Packages: List, search, install, remove, embed, and configure Unity packages and scoped registries.
Read Console: Retrieve or clear Unity Editor console messages with filtering by type and text.
Unity Reflect: Inspect Unity's live C# API via reflection — look up types, members, and assemblies.
Execute Menu Items: Trigger any Unity Editor menu item by path.
Refresh Unity: Trigger asset database refresh and/or script compilation.
Set Active Instance: Pin a specific Unity Editor instance when multiple are running.
The proxy layer also enforces tool allowlists, corrects false failure responses (e.g., for asset move/rename/delete), applies a per-call watchdog timer, and blocks schema-drifted tools.
Provides a proxy to the MCP-for-Unity server, enabling AI agents to interact with Unity by exposing tools for code execution, asset management, and console output correction, with additional safety and idempotency guards.
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., "@vrc-mcp-proxy Move the 'Player' prefab to the 'Resources' folder."
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.
vrc-mcp-proxy
Developed in the Atelier workspace.
An owned stdio MCP interception proxy that wraps the pinned MCP-for-Unity server (version pinned in src/vrc_mcp_proxy/config.py, via uvx) and corrects a handful of ways its transport lies to the model — a snippet silently executed twice by a connection-level retry, a timeout that doesn't mean the work didn't run, a target-lookup miss that only means the object was inactive. It also narrows the exposed tool surface to an allowlist and refuses execute_code snippets that can't compile in a method body.
Some lies are refused rather than corrected, because the truth never reaches this process. read_console truncates every console entry to its first line inside Unity, so a multi-line diagnostic's payload is already gone; the refusal routes to ReportConsole (com.ryan6vrc.agent-tools), which reads UnityEditor.LogEntries directly. manage_asset's move/rename discards AssetDatabase.MoveAsset's return value and substitutes a verdict that reports failure on moves that landed; the refusal routes to that API, whose empty-or-error string separates the cases nothing downstream can. A lie the proxy cannot see is a lie it must not appear to have handled.
It is a thin line-based JSON-RPC relay, not an MCP-SDK re-serve: it spawns the pinned server as a subprocess and passes every message through untouched except at named interception points. See docs/design.md for the full rationale and the per-failure verdicts, and docs/bump-runbook.md for moving the upstream pin.
Every interception point below runs inside a contained region, so one raising transform cannot take the relay down and leave the session mute. Containment is always on and has no VRC_MCP_PROXY_DISABLE name — it is not a behavior in the table's sense. docs/design.md §Three standing rules owns what a caller is told when a region fails, and which classes fail open rather than loud.
Behaviors
Behavior | Point | What it does |
| tools/list resp | Validates upstream schemas against the committed baseline; refuses calls to a tool whose schema drifted. |
| tools/list resp + tools/call req | Exposes only the allowlisted tools; refuses the rest, naming the one-line fix. |
| tools/call req | Refuses snippets with top-level |
| tools/call req | Wraps snippets in a SessionState guard so an upstream transport re-send returns the cached result instead of running twice. |
| tools/call req | Refuses |
| tools/call resp | On a |
| tools/call resp | Appends a note to timeout errors: the work may have run; verify on disk before retrying. |
| tools/call resp | On an |
| tools/call resp | On an |
| tools/call req + timer | Per-call timer on an |
| tools/call req | Refuses an unpinned call while 2+ Unity editors are live (probe-free heartbeat count), naming them and |
| tools/call req + resp | Prepends an exact |
| tools/call resp ( | On a successful pin, surfaces the resolved project root as |
| tools/call resp | On an upstream instance-not-found error, when this machine's heartbeat files still name that instance, appends what the proxy can measure — the heartbeat's age and reason — and the cure that follows from it. Upstream drops an instance whose port fails a 0.3s framed ping, so a fresh |
| tools/call req | Sends |
| tools/call req | Refuses a |
| tools/call req | Refuses a |
| tools/call resp | On a |
| tools/call resp | On a |
| tools/call req | Defaults a |
Related MCP server: revula
Wiring it into .mcp.json
Keep the server key UnityMCP so every mcp__UnityMCP__* name and settings matcher survives unchanged:
{
"mcpServers": {
"UnityMCP": {
"command": "uv",
"args": ["run", "--project", "<path-to-this-repo>", "vrc-mcp-proxy"]
}
}
}The proxy spawns the pinned upstream server itself; you do not point .mcp.json at uvx mcpforunityserver anymore.
Disabling a behavior
Each behavior is independently disableable at launch via one env var (comma- or space-separated names from the table above):
"env": { "VRC_MCP_PROXY_DISABLE": "manage_asset_mutation_guard,canary" }Development
uv run pytestTests need no Unity: transforms are unit-tested as pure functions, and one end-to-end test relays the proxy against a scripted fake child process. The pin lives in exactly one place — src/vrc_mcp_proxy/config.py.
Available Tools
14 toolsdebug_request_contextDebug Request ContextARead-only
Return the current FastMCP request context details (client_id, session_id, and meta dump).
Inputs: no named parameters. Returns: object
execute_codeExecute CodeADestructive
Execute arbitrary C# code inside the Unity Editor. The code runs as a method body with access to UnityEngine and UnityEditor namespaces. Use 'return' to send data back. Compiled in-memory — no script files created. Actions: execute (run code), get_history (list past executions), replay (re-run a history entry), clear_history. NOTE: safety_checks blocks known dangerous patterns but is not a full sandbox. Compiler options: 'auto' (Roslyn if available, else CodeDom), 'roslyn' (C# 12+, requires Microsoft.CodeAnalysis), 'codedom' (C# 6 only).
Inputs: action (required), code, index, limit, +2 more. Returns: object
find_gameobjectsA
Search for GameObjects in the scene by name, tag, layer, component type, or path. Returns instance IDs only (paginated). Then use mcpforunity://scene/gameobject/{id} resource for full data, or mcpforunity://scene/gameobject/{id}/components for component details. For CRUD operations (create/modify/delete), use manage_gameobject instead.
Inputs: search_term (required), cursor, page_size, search_method, +1 more. Returns: object
manage_assetManage AssetADestructive
Performs asset operations (import, create, modify, delete, etc.) in Unity.
Tip (payload safety): for action="search", prefer paging (page_size, page_number) and keep generate_preview=false (previews can add large base64 blobs).
Inputs: path (required), action (required), page_size, asset_type, +7 more. Returns: object
manage_cameraManage CameraADestructive
Manage cameras (Unity Camera + Cinemachine). Works without Cinemachine using basic Camera; unlocks presets, pipelines, and blending when Cinemachine is installed. Use ping to check Cinemachine availability.
SETUP:
ping: Check if Cinemachine is available
ensure_brain: Ensure CinemachineBrain exists on main camera
get_brain_status: Get Brain state (active camera, blend, etc.)
CAMERA CREATION:
create_camera: Create camera with preset (third_person, freelook, follow, dolly, static, top_down, side_scroller). Falls back to basic Camera without Cinemachine.
CAMERA CONFIGURATION:
set_target: Set Follow and/or LookAt targets on a camera
set_priority: Set camera priority for Brain selection
set_lens: Configure lens (fieldOfView, nearClipPlane, farClipPlane, orthographicSize, dutch)
set_body: Configure Body component (bodyType to swap, plus component properties)
set_aim: Configure Aim component (aimType to swap, plus component properties)
set_noise: Configure Noise component (amplitudeGain, frequencyGain)
EXTENSIONS:
add_extension: Add extension (extensionType: CinemachineConfiner2D, CinemachineDeoccluder, CinemachineImpulseListener, CinemachineFollowZoom, CinemachineRecomposer, etc.)
remove_extension: Remove extension by type
CAMERA CONTROL:
set_blend: Configure default blend (style: Cut/EaseInOut/Linear/etc., duration)
force_camera: Override Brain to use specific camera
release_override: Release camera override
list_cameras: List all cameras with status
CAPTURE:
screenshot: Capture a screenshot. By default (no camera specified) uses ScreenCapture API, which captures all render layers including Screen Space - Overlay UI canvases. Specifying a camera uses direct camera rendering, which EXCLUDES Screen Space - Overlay canvases (use only when you need a specific viewpoint without UI). Supports include_image=true for inline base64 PNG, batch='surround' for 6-angle contact sheet, batch='orbit' for configurable grid, view_target/view_position for positioned capture, and capture_source='scene_view' to capture the active Unity Scene View viewport.
screenshot_multiview: Shorthand for screenshot with batch='surround' and include_image=true.
Inputs: action (required), batch, camera, target, +15 more.
manage_editorManage EditorA
Controls and queries the Unity editor's state and settings. Read-only actions: telemetry_status, telemetry_ping. Modifying actions: play, pause, stop, set_active_tool, add_tag, remove_tag, add_layer, remove_layer, deploy_package, restore_package, undo, redo. For prefab editing (open/save/close prefab stage), use manage_prefabs. deploy_package copies the configured MCPForUnity source folder into the project's installed package location (triggers recompile, no confirmation dialog). restore_package reverts to the pre-deployment backup. undo/redo perform Unity editor undo/redo and return the affected group name.
Inputs: action (required), tag_name, tool_name, layer_name. Returns: object
manage_gameobjectManage GameObjectADestructive
Performs CRUD operations on GameObjects. Actions: create, modify, delete, duplicate, move_relative, look_at. NOT for searching — use the find_gameobjects tool to search by name/tag/layer/component/path. NOT for component management — use the manage_components tool (add/remove/set_property) or mcpforunity://scene/gameobject/{id}/components resource (read).
Inputs: tag, name, layer, scale, +23 more. Returns: object
manage_packagesManage PackagesADestructive
Manage Unity packages: query, install, remove, embed, and configure registries.
QUERY (read-only):
list_packages: List all installed packages
search_packages: Search Unity registry by keyword
get_package_info: Get details about a specific installed package
ping: Check package manager availability
status: Poll async job status (job_id required for list/search; optional for add/remove/embed)
INSTALL/REMOVE:
add_package: Install a package (name, name@version, git URL, or file: path)
remove_package: Remove a package (checks dependents; use force=true to override)
REGISTRIES:
list_registries: List all scoped registries
add_registry: Add a scoped registry (e.g., OpenUPM)
remove_registry: Remove a scoped registry
UTILITY:
embed_package: Copy package to local Packages/ for editing
resolve_packages: Force re-resolution of all packages
Inputs: action (required), url, name, force, +4 more. Returns: object
manage_sceneManage SceneADestructive
Performs CRUD operations on Unity scenes. Read-only actions: get_hierarchy, get_active, get_build_settings, get_loaded_scenes, scene_view_frame. Modifying actions: create (with optional template), load (with optional additive flag), save, close_scene, set_active_scene, move_to_scene, validate (with optional auto_repair). For build settings management (add/remove/enable scenes), use manage_build(action='scenes'). For screenshots, use manage_camera (screenshot, screenshot_multiview actions).
Inputs: action (required), name, path, cursor, +15 more. Returns: object
read_consoleRead ConsoleA
Gets messages from or clears the Unity Editor console. Defaults to 10 most recent entries. Use page_size/cursor for paging. Note: For maximum client compatibility, pass count as a quoted string (e.g., '5'). The 'get' action is read-only; 'clear' modifies ephemeral UI state (not project data).
Inputs: count, types, action, cursor, +4 more. Returns: object
refresh_unityRefresh UnityADestructive
Request a Unity asset database refresh and optionally a script compilation. Can optionally wait for readiness.
Inputs: mode, scope, compile, wait_for_ready. Returns: result
set_active_instanceSet Active InstanceA
Set the active Unity instance for this client/session. Accepts Name@hash, hash prefix, or port number (stdio only).
Inputs: instance (required). Returns: object
unity_reflectUnity ReflectARead-only
Inspect Unity's live C# API via reflection. Use this to verify that classes, methods, and properties exist before writing C# code — training data may be wrong or outdated.
Actions:
get_type: Member summary (names only) for a class. Requires class_name.
get_member: Full signature detail for one member. Requires class_name + member_name.
search: Type name search across loaded assemblies. Requires query. Optional scope.
Inputs: action (required), query, scope, class_name, +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool targets a distinct operation (debugging, code execution, game object CRUD, scene management, etc.) with no overlap. Descriptions clearly differentiate similar-sounding tools like manage_gameobject vs find_gameobjects.
Most tools use a verb_noun pattern (e.g., execute_code, find_gameobjects, manage_scene). The only exception is unity_reflect (noun_verb), but it's a single deviation from an otherwise consistent convention.
14 tools cover a broad range of Unity editor operations without being overwhelming. The count is well-suited for the server's purpose of comprehensive editor control via MCP.
The tool surface covers core workflows like CRUD on game objects, scenes, assets, packages, camera control, and editor state. Minor gaps exist (e.g., no dedicated animation or UI tools), but the set is functional and extendable.
Related MCP Connectors
MCP server for developer documentation, generated by doc2mcp.
The official MCP Server for the Mux API
Related MCP Servers
- FlicenseBqualityCmaintenanceMCP server for high-fidelity code audits, refactoring, and architectural analysis using specialized Proxy Experts.85-
- AlicenseNot gradedqualityDmaintenanceProduction-grade MCP server for universal reverse engineering automation.85GPL 3.0
- AlicenseAqualityCmaintenanceAn MCP server that recovers original C# class, method, field, and parameter names from Unity IL2CPP global-metadata.dat files to assist with reverse engineering Unity games.14MIT
- FlicenseNot gradedqualityDmaintenanceA sandbox MCP server for testing and debugging MCP tools and interactions via the MCP Inspector.-