codex-tuanjie-mcp
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., "@codex-tuanjie-mcp start the project and list all GameObjects in the current scene"
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.
Codex Tuanjie MCP
This is a local STDIO MCP adapter for Codex. It reuses the official cn.tuanjie.codely.bridge Package in the Tuanjie engine, allowing Codex to launch a specified Tuanjie project and operate the editor, scenes, GameObjects, scripts, assets, and console through Codely Bridge.
Codex
-> MCP STDIO
-> codex-tuanjie-mcp
-> Codely Bridge TCP
-> Tuanjie EditorThis project does not replace or modify the Codely Bridge implementation. The adapter is only responsible for discovering the Bridge, completing the TCP protocol handshake, validating the target project, and converting Bridge commands into MCP tools.
Current Capabilities
Initialize and launch an existing Tuanjie project via
tuanjie_start.When the project lacks the Bridge, add the official
cn.tuanjie.codely.bridgedependency toPackages/manifest.json.Create a timestamped backup in the same directory before modifying the manifest.
Launch the project via
tuanjie.exe open <project>; reuse it directly if the project is already open.Wait for
.com-unity-codely.jsonto becomeready, connect to the dynamic port, and validate the project root directory.After an editor reload or port change, automatically rediscover and reconnect before the next tool call.
Expose 22 MCP tools covering the editor, scenes, GameObjects, scripts, Shaders, assets, Packages, UI Toolkit, screenshots, Game View, input simulation, console, async tasks, and C# execution.
Current boundary: the MCP must be bound to a project already created by Tuanjie Hub. It does not currently create Tuanjie projects from empty directories, nor does it automatically switch between multiple projects.
Related MCP server: Unity MCP
Prerequisites
1. Install Software
Windows 10 or later.
Node.js 20 or later.
Codex Desktop or Codex CLI.
Tuanjie Cowork, along with the required version of the Tuanjie engine and Tuanjie Hub.
Tuanjie engine 2021.3 or later. The official Codely Bridge documentation requires Unity/Tuanjie engine 2021.3 or later.
After installing or updating Tuanjie Cowork, restart Cowork and Codex to ensure the tuanjie.exe it provides is visible to the MCP process. You can verify first:
tuanjie.exe --help
tuanjie.exe editors list-installed2. Create a Project in Tuanjie Hub
First create and register a project through Tuanjie Hub, and confirm the project root directory contains at least:
Assets/
Packages/manifest.json
ProjectSettings/ProjectVersion.txtYou can also create a project with the Tuanjie CLI, but you must first determine the public 1.x.x engine version and the exact template ID:
tuanjie.exe template list 1.10.1
tuanjie.exe projects create "MyGame" `
--path "D:\games" `
--editor-version 1.10.1 `
--template "<template-id>"Do not pass internal editor versions like 2022.3.xxtxx to --editor-version; use the public 1.x.x version shown in Hub.
3. Prepare Codely Bridge
Manual installation is usually not needed. On the first call to tuanjie_start, if the project manifest has no Bridge, the MCP queries the official Tuanjie Package Registry, writes the dependency, then launches the editor and waits for Package Manager to finish the installation.
To install manually, open the following in the Tuanjie editor:
Window -> Package Manager -> Tuanjie RegistrySearch for Tuanjie AI and install Codely Bridge. See the Codely Bridge Installation Guide for official instructions.
Development and Build
Clone the repository:
git clone https://github.com/g82v68xftk-ux/codex-tuanjie-mcp.git
Set-Location codex-tuanjie-mcpRun in the source directory:
npm ci
npm testnpm test first runs the TypeScript build, then runs tests for protocol framing, config discovery, Bridge handshake, request correlation, Package initialization, and project launch. To build alone, run:
npm run buildInstalling into Codex
By convention, each MCP uses its own dedicated directory:
C:\Users\<username>\.codex\mcp\codex-tuanjie-mcpPlace the built dist, package.json, package-lock.json, and this README into that directory, then install runtime dependencies in the installation directory:
npm ci --omit=devRegister the MCP and bind it to the target Tuanjie project:
codex mcp add tuanjie -- node `
"C:\Users\<username>\.codex\mcp\codex-tuanjie-mcp\dist\src\index.js" `
--project "D:\path\to\tuanjie-project"Check the registration result:
codex mcp get tuanjieAfter registering or updating the MCP, create a new Codex task or restart Codex; already-running tasks will not dynamically load newly added tools.
Usage
Launch and Connect to a Project
In Codex, simply ask to "launch the Tuanjie project", or explicitly call tuanjie_start:
{
"install_bridge": true,
"wait_timeout_seconds": 300
}The execution flow is as follows:
验证项目
-> 检查/安装 Codely Bridge
-> 检查现有 Bridge 连接
-> 必要时调用 tuanjie.exe open
-> 等待 Bridge ready
-> 连接并验证项目根目录Optional parameters:
install_bridge: defaults totrue. When set tofalse, the project must already have the Bridge installed.bridge_package_version: specifies the Bridge Package version; when omitted, the official Registry is queried.wait_timeout_seconds: time to wait for the editor and Bridge, default 300 seconds, range 10-900 seconds.
Check the Connection
tuanjie_bridge_status: reads the Bridge configuration and current connection status without actively reconnecting.unity_refresh: re-reads the dynamic port, reconnects, and validates the project root directory.
Once connected, you can use tools such as unity_editor, unity_scene, unity_gameobject, unity_script, and unity_asset to operate on the project.
Configuration Discovery Order
The adapter locates the Bridge in the following order:
--config <path>orTUANJIE_BRIDGE_CONFIG.--project <path>orTUANJIE_PROJECT_PATH.The MCP process working directory and its parent directories.
It is recommended to always use --project in the Codex registration parameters to explicitly bind the project, avoiding connections to the wrong editor instance.
Verification and Diagnostics
Probe the Bridge against an actual project:
npm run probe -- --project "D:\path\to\tuanjie-project"Run tool listing, launch, status, and editor read verification through real MCP STDIO:
npm run smoke:mcp -- --project "D:\path\to\tuanjie-project"Common issues:
tuanjie.exenot found: install or update Tuanjie Cowork, then restart Cowork and Codex.tuanjie_startmissing in Codex: create a new task or restart Codex, and confirmcodex mcp get tuanjieshowsenabled: true.Bridge wait timeout: check whether the editor is blocked by login, license, Package installation, or compilation dialogs.
Project mismatch: check whether
--projectin the MCP registration points to the project currently open in the editor.MCP tools unavailable: check the Codex MCP logs, as well as
C:\Users\<username>\.codely\logs.
Security Boundaries
The MCP does not automatically pop up the editor at startup; only an explicit call to
tuanjie_startlaunches the project.Commands already sent to the Bridge are not automatically retried after a connection error, to avoid re-executing write operations.
Play Mode write restrictions are still determined by the official Codely Bridge.
execute_csharp_scriptand most administrative tools can modify the project; use them in a Git working tree.When the Bridge already exists,
Packages/manifest.jsonis not rewritten; when the Bridge is missing, a backup is made before modifying.
Project Structure
src/
bridge-client.ts Bridge TCP 握手、连接和请求处理
config.ts .com-unity-codely.json 发现与解析
framing.ts 8 字节大端长度帧编码/解码
project-start.ts Bridge 初始化、tuanjie.exe 启动和 ready 等待
tool-definitions.ts MCP 工具定义
index.ts STDIO MCP 服务入口
test/ Node.js 测试Protocol Notes
Bridge welcome message:
WELCOME UNITY-TCP 1 FRAMING=1 SERVER_VERSION=2.Client frame:
CLIENT_VERSION=2,PLATFORM=codex.Data frames use an 8-byte unsigned big-endian length prefix.
Maximum single frame size is 64 MiB.
Each command contains
type,params, andrequest_id.
License
This project is licensed under the MIT License.
Available Tools
22 toolsexecute_csharp_scriptExecute C# in TuanjieADestructive
Executes inline C# or an existing .cs file through the official Bridge. Provide script or script_path. This can mutate the project or editor state.
Inputs: script, summary, script_path, capture_logs, +2 more.
execute_custom_toolExecute Custom Tuanjie ToolBDestructive
Executes a custom tool registered by the official Codely Bridge package. Pass tool_name and an optional parameters object.
Inputs: tool_name (required), parameters.
tuanjie_bridge_statusTuanjie Bridge StatusARead-onlyIdempotent
Reads the active .com-unity-codely.json and reports the adapter connection state without reconnecting.
Inputs: no named parameters.
tuanjie_startInitialize and Start TuanjieA
Ensures the official Codely Bridge package is present in the configured project, opens that project with tuanjie.exe, waits for Bridge readiness, and verifies the connected project. If the editor is already connected, it is reused. This can update Packages/manifest.json when the Bridge package is missing.
Inputs: install_bridge, wait_timeout_seconds, bridge_package_version.
unity_assetTuanjie Asset ManagerADestructive
Creates, imports, modifies, searches, and inspects project assets. Supported actions: create_batch, edit_batch, ensure_has_meta, ensure_meta_integrity, import, create, modify, delete, duplicate, move, rename, search, get_info, create_folder, get_components. Additional action-specific parameters are passed through unchanged.
Inputs: action (required).
unity_bakeTuanjie Bake ManagerBDestructive
Starts, waits for, or clears navigation and lighting bakes. Supported actions: bake_navmesh, bake_lighting, wait_for_bake, clear_navmesh, clear_baked_data. Additional action-specific parameters are passed through unchanged.
Inputs: action (required).
unity_consoleTuanjie Console ReaderBDestructive
Reads or clears Tuanjie Editor console entries. Supported actions: get, clear. Additional action-specific parameters are passed through unchanged.
Inputs: action (required).
unity_custom_toolsList Custom Tuanjie ToolsARead-onlyIdempotent
Lists custom tools registered by project extensions in the official Codely Bridge. Use the returned names with execute_custom_tool.
Inputs: no named parameters.
unity_dialogTuanjie Dialog ManagerBDestructive
Clicks a button in a modal editor dialog. Supported actions: click. Additional action-specific parameters are passed through unchanged.
Inputs: action (required).
unity_editorTuanjie Editor ControllerCDestructive
Controls and inspects the Tuanjie Editor. Supported actions: publish_dirty_state_if_needed, wait_for_compile, wait_for_stop, request_compile, start_compilation_pipeline, get_compilation_summary, wait_for_idle, play, pause, stop, step, get_state, get_current_state, get_project_root, get_windows, get_active_tool, get_selection, drain_agent_input, set_active_tool, ensure_tag, add_tag, remove_tag, get_tags, ensure_layer, add_layer, remove_layer, get_layers, focus_window. Additional action-specific parameters are passed through unchanged.
Inputs: action (required).
unity_gameobjectTuanjie GameObject ManagerADestructive
Creates, modifies, finds, and inspects GameObjects and components. Supported actions: create_batch, edit_batch, ensure_component, ensure_renderer_material, ensure_mesh_collider_mesh, ensure_prefab_default_sprite, create, modify, delete, find, list_children, get_components, add_component, remove_component, set_component_property, select. Additional action-specific parameters are passed through unchanged.
Inputs: action (required).
unity_gameviewTuanjie Game View ResolutionADestructive
Reads or changes the Game View resolution. Supported actions: get_resolution, set_resolution, list_resolutions. Additional action-specific parameters are passed through unchanged.
Inputs: action (required).
unity_inputTuanjie Input SimulatorADestructive
Simulates mouse, keyboard, and virtual input devices, primarily in Play Mode. Supported actions: mouse_click, mouse_move, mouse_drag, mouse_scroll, mouse_down, mouse_up, key_press, key_down, key_up, type_text, create_virtual_devices, destroy_virtual_devices. Additional action-specific parameters are passed through unchanged.
Inputs: action (required).
unity_jobTuanjie Job ManagerBDestructive
Checks, lists, or cancels asynchronous Bridge jobs. Supported actions: status, check, list, cancel. Additional action-specific parameters are passed through unchanged.
Inputs: action (required).
unity_packageTuanjie Package ManagerADestructive
Installs, removes, waits for, or lists UPM packages. Supported actions: install_package, remove_package, wait_for_upm, list_packages. Additional action-specific parameters are passed through unchanged.
Inputs: action (required).
unity_refreshRefresh Tuanjie Bridge ConnectionARead-onlyIdempotent
Re-reads .com-unity-codely.json, reconnects to the current dynamic Bridge port, and verifies the project root.
Inputs: no named parameters.
unity_sceneTuanjie Scene ManagerADestructive
Creates, opens, saves, and inspects scenes. Supported actions: ensure_scene_open, ensure_scene_saved, create, load, save, get_hierarchy, get_active, get_build_settings. Additional action-specific parameters are passed through unchanged.
Inputs: action (required).
unity_screenshotTuanjie Screenshot CaptureBDestructive
Captures editor, scene, camera, asset, or UI views and controls Game View recording. Supported actions: capture_game_view, capture, capture_scene_view, capture_scene_camera, capture_main_camera, capture_specific_camera, capture_asset, capture_ui_toolkit, start_game_view_recording, finish_game_view_recording. Additional action-specific parameters are passed through unchanged.
Inputs: action (required).
unity_scriptTuanjie Script ManagerCDestructive
Creates, reads, edits, validates, and deletes C# scripts under Assets. Supported actions: create, read, update, delete, apply_text_edits, validate, edit, get_sha. Additional action-specific parameters are passed through unchanged.
Inputs: action (required).
unity_shaderTuanjie Shader ManagerCDestructive
Inspects render pipelines and manages shader compilation or previews. Supported actions: detect_render_pipeline, ensure_material_shader_for_srp, compile, preview. Additional action-specific parameters are passed through unchanged.
Inputs: action (required).
unity_ui_toolkitTuanjie UI Toolkit ManagerBDestructive
Creates and links UI Toolkit assets. Supported actions: ensure_panel_settings_asset, link_uss_to_uxml, create_uxml, create_uss. Additional action-specific parameters are passed through unchanged.
Inputs: action (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 22 tools
Tools are grouped by clear editor subsystems (asset, scene, GameObject, package, console), so an agent can usually choose the right one from the name. A few overlaps exist—unity_asset and unity_gameobject both expose get_components, and shader/editor compile actions could be confused—but descriptions keep boundaries mostly clear.
Names are consistently lowercase snake_case and follow a recognizable prefix taxonomy: unity_* for editor subsystems, tuanjie_* for bridge lifecycle, and execute_* for generic execution. The main inconsistency is that names are domain nouns rather than verb_noun action names, with a few outliers like execute_custom_tool and unity_custom_tools.
22 tools is on the heavy side, and each tool bundles many sub-actions, making the effective surface much larger than the count suggests. The breadth is justified by the editor-automation domain, but the toolset feels borderline over-scoped rather than tight.
The server covers the major editor workflows: connection/startup, assets, scenes, GameObjects, scripts, packages, UI, input, screenshots, console, baking, and editor state. Obvious gaps like build/player settings or dedicated prefab/animation tools exist, but they are workable gaps rather than critical dead ends.
Maintenance
Related MCP Connectors
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
Build, run and publish 3D games in the Zero engine from Claude Code, Cursor or Codex, over MCP.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceA bridge enabling seamless communication between Unity and Large Language Models via the Model Context Protocol, allowing developers to automate workflows, manipulate assets, and control the Unity Editor programmatically.16,080MIT
- AlicenseNot gradedqualityDmaintenanceConnects Claude Code to the Unity Editor via MCP, enabling AI-driven control of scenes, assets, components, UI, animations, and more through 91 tools.2MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI tools to connect to and control Unity/Tuanjie editors via the Codely Bridge TCP server, supporting project management, scene manipulation, and console reading.3-
- AlicenseNot gradedqualityBmaintenanceBridges the Unity Editor with AI assistants via MCP, enabling AI tools to control and interact with Unity projects. Supports multi-project routing and automatic first-launch server deployment.MIT