Skip to main content
Glama

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 Editor

This 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.bridge dependency to Packages/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.json to become ready, 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-installed

2. 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.txt

You 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 Registry

Search 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-mcp

Run in the source directory:

npm ci
npm test

npm 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 build

Installing into Codex

By convention, each MCP uses its own dedicated directory:

C:\Users\<username>\.codex\mcp\codex-tuanjie-mcp

Place 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=dev

Register 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 tuanjie

After 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 to true. When set to false, 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:

  1. --config <path> or TUANJIE_BRIDGE_CONFIG.

  2. --project <path> or TUANJIE_PROJECT_PATH.

  3. 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.exe not found: install or update Tuanjie Cowork, then restart Cowork and Codex.

  • tuanjie_start missing in Codex: create a new task or restart Codex, and confirm codex mcp get tuanjie shows enabled: true.

  • Bridge wait timeout: check whether the editor is blocked by login, license, Package installation, or compilation dialogs.

  • Project mismatch: check whether --project in 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_start launches 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_script and most administrative tools can modify the project; use them in a Git working tree.

  • When the Bridge already exists, Packages/manifest.json is 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, and request_id.

License

This project is licensed under the MIT License.

Available Tools

22 tools
execute_csharp_scriptExecute C# in TuanjieA
Destructive

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 ToolB
Destructive

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 StatusA
Read-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 ManagerA
Destructive

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 ManagerB
Destructive

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 ReaderB
Destructive

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 ToolsA
Read-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 ManagerB
Destructive

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 ControllerC
Destructive

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 ManagerA
Destructive

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 ResolutionA
Destructive

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 SimulatorA
Destructive

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 ManagerB
Destructive

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_menuTuanjie Menu ExecutorC
Destructive

Lists or executes Tuanjie Editor menu items. Supported actions: execute, get_available_menus. Additional action-specific parameters are passed through unchanged.

Inputs: action (required).

unity_packageTuanjie Package ManagerA
Destructive

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 ConnectionA
Read-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 ManagerA
Destructive

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 CaptureB
Destructive

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 ManagerC
Destructive

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 ManagerC
Destructive

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 ManagerB
Destructive

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

    B3.2/5.0

    Scored across 22 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      A 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,080
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects Claude Code to the Unity Editor via MCP, enabling AI-driven control of scenes, assets, components, UI, animations, and more through 91 tools.
      2
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Bridges 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