Godot MCP

Instructions

Implementation Reference

• src/godot_mcp/godot.py:1291-1385 (handler)

  The handler method `add_primitive_mesh` in `GodotController` which executes the logic for adding a primitive mesh.

  def add_primitive_mesh(
      self,
      project_path: str,
      scene_path: str,
      mesh_type: str,
      parent_path: str = ".",
      node_name: str | None = None,
      mesh_parameters: dict[str, Any] | None = None,
      transform: dict[str, Any] | None = None,
      godot_executable: str | None = None,
  ) -> dict[str, Any]:
      project_dir = ensure_project_path(project_path)
      executable, version = resolve_godot_executable(godot_executable)
      absolute_scene_path, resource_scene_path = resolve_scene_path(project_dir, scene_path)
  
      if not absolute_scene_path.exists():
          raise GodotError(f"Scene not found: {absolute_scene_path}")
  
      final_mesh_type = mesh_type.strip()
      if not final_mesh_type:
          raise GodotError("`mesh_type` is required.")
  
      normalized_parent_path = normalize_scene_node_path(parent_path)
      final_node_name = (node_name or "").strip()
      if not final_node_name:
          base_name = final_mesh_type[:-4] if final_mesh_type.lower().endswith("mesh") else final_mesh_type
          final_node_name = pascal_case_name(base_name, default="Mesh")
  
      final_mesh_parameters = mesh_parameters or {}
      if not isinstance(final_mesh_parameters, dict):
          raise GodotError("`mesh_parameters` must be an object when provided.")
      final_transform = transform or {}
      if not isinstance(final_transform, dict):
          raise GodotError("`transform` must be an object when provided.")
  
      payload = {
          "mesh_parameters": final_mesh_parameters,
          "transform": final_transform,
      }
      try:
          with tempfile.NamedTemporaryFile(
              mode="w",
              encoding="utf-8",
              suffix="-godot-primitive-mesh.json",
              delete=False,
          ) as handle:
              json.dump(payload, handle, ensure_ascii=False)
              config_path = handle.name
      except TypeError as exc:
          raise GodotError(
              "`mesh_parameters` or `transform` contains a value that could not be serialized to JSON."
          ) from exc
  
      try:
          output = _run_godot_script(
              executable=executable,
              project_dir=project_dir,
              script_name="add_primitive_mesh.gd",
              user_args=[
                  "--scene-path",
                  resource_scene_path,
                  "--parent-path",
                  normalized_parent_path,
                  "--node-name",
                  final_node_name,
                  "--mesh-type",
                  final_mesh_type,
                  "--config-path",
                  config_path,
              ],
          )
      finally:
          Path(config_path).unlink(missing_ok=True)
  
      parsed = _parse_script_json_output(output, "add_primitive_mesh.gd")
      supported_mesh_parameters = parsed.get("supported_mesh_parameters", [])
      if not isinstance(supported_mesh_parameters, list):
          raise GodotError("Primitive mesh creation did not return a supported parameter list.")
  
      return {
          "project_path": str(project_dir),
          "scene_path": str(absolute_scene_path),
          "scene_resource_path": resource_scene_path,
          "parent_path": parsed.get("parent_path", normalized_parent_path),
          "node_path": parsed.get("node_path"),
          "node_name": parsed.get("node_name", final_node_name),
          "node_type": parsed.get("node_type", "MeshInstance3D"),
          "mesh_type": parsed.get("mesh_type", final_mesh_type),
          "mesh_parameters": parsed.get("mesh_parameters", {}),
          "supported_mesh_parameters": supported_mesh_parameters,
          "updated_mesh_parameters": parsed.get("updated_mesh_parameters", []),
          "transform": parsed.get("transform", {}),
          "godot_executable": str(executable),
          "godot_version": version,
      }

• src/godot_mcp/server.py:547-599 (registration)

  Tool registration for `godot_add_primitive_mesh` in `server.py`.

      name="godot_add_primitive_mesh",
      description="Add a MeshInstance3D with a built-in PrimitiveMesh resource such as BoxMesh, CylinderMesh, SphereMesh, CapsuleMesh, PlaneMesh, PrismMesh, QuadMesh, or TorusMesh.",
      input_schema={
          "type": "object",
          "properties": {
              "project_path": {
                  "type": "string",
                  "description": "Path to the Godot project directory or its project.godot file.",
              },
              "scene_path": {
                  "type": "string",
                  "description": "Path to the target .tscn file. Absolute, relative, and res:// paths are supported.",
              },
              "mesh_type": {
                  "type": "string",
                  "description": "Primitive mesh class to instantiate, such as BoxMesh, CylinderMesh, SphereMesh, CapsuleMesh, PlaneMesh, PrismMesh, QuadMesh, or TorusMesh.",
              },
              "parent_path": {
                  "type": "string",
                  "description": "Scene-relative node path where the new mesh node should be attached. Use '.' for the root.",
                  "default": ".",
              },
              "node_name": {
                  "type": "string",
                  "description": "Optional explicit MeshInstance3D node name. Defaults to a PascalCase form of the mesh type without a trailing Mesh suffix.",
              },
              "mesh_parameters": {
                  "type": "object",
                  "description": "Optional primitive mesh property overrides such as size, radius, height, or segment counts.",
              },
              "transform": {
                  "type": "object",
                  "description": "Optional Node3D transform fields to apply to the new MeshInstance3D. Vector values can be passed as objects like {x, y, z}.",
              },
              "godot_executable": {
                  "type": "string",
                  "description": "Optional explicit path to the Godot executable or .app bundle.",
              },
          },
          "required": ["project_path", "scene_path", "mesh_type"],
          "additionalProperties": False,
      },
      handler=lambda args: self.controller.add_primitive_mesh(
          project_path=args["project_path"],
          scene_path=args["scene_path"],
          mesh_type=args["mesh_type"],
          parent_path=args.get("parent_path", "."),
          node_name=args.get("node_name"),
          mesh_parameters=args.get("mesh_parameters"),
          transform=args.get("transform"),
          godot_executable=args.get("godot_executable"),
      ),
  ),