Godot MCP

Instructions

Implementation Reference

• src/godot_mcp/godot.py:1825-1894 (handler)

  Implementation of the update_project_settings logic in the GodotController class.

  def update_project_settings(
      self,
      project_path: str,
      settings: list[dict[str, Any]],
      godot_executable: str | None = None,
  ) -> dict[str, Any]:
      project_dir = ensure_project_path(project_path)
      executable, version = resolve_godot_executable(godot_executable)
  
      if not settings:
          raise GodotError("`settings` must contain at least one setting update.")
  
      normalized_settings: list[dict[str, Any]] = []
      for index, item in enumerate(settings):
          if not isinstance(item, dict):
              raise GodotError(f"`settings[{index}]` must be an object.")
  
          setting_name = str(item.get("name", "")).strip()
          if not setting_name:
              raise GodotError(f"`settings[{index}].name` is required.")
  
          has_value = "value" in item
          has_value_godot = str(item.get("value_godot", "")).strip() != ""
          if has_value == has_value_godot:
              raise GodotError(
                  f"`settings[{index}]` must include exactly one of `value` or `value_godot`."
              )
  
          normalized_item = {"name": setting_name}
          if has_value_godot:
              normalized_item["value_godot"] = str(item["value_godot"])
          else:
              normalized_item["value"] = item["value"]
          normalized_settings.append(normalized_item)
  
      try:
          with tempfile.NamedTemporaryFile(
              mode="w",
              encoding="utf-8",
              suffix="-godot-project-settings.json",
              delete=False,
          ) as handle:
              json.dump(normalized_settings, handle, ensure_ascii=False)
              updates_path = handle.name
      except TypeError as exc:
          raise GodotError("`settings` 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="update_project_settings.gd",
              user_args=["--updates-path", updates_path],
          )
      finally:
          Path(updates_path).unlink(missing_ok=True)
  
      parsed = _parse_script_json_output(output, "update_project_settings.gd")
      updated_settings = parsed.get("updated_settings")
      if not isinstance(updated_settings, list):
          raise GodotError("Project settings update did not return a settings list.")
  
      return {
          "project_path": str(project_dir),
          "project_file": str(project_dir / "project.godot"),
          "updated_count": len(updated_settings),
          "updated_settings": updated_settings,
          "godot_executable": str(executable),
          "godot_version": version,
      }

• src/godot_mcp/server.py:339-384 (registration)

  Registration of the godot_update_project_settings tool within the GodotMcpServer class.

      name="godot_update_project_settings",
      description="Update one or more ProjectSettings values and save them back to the Godot project through Godot itself.",
      input_schema={
          "type": "object",
          "properties": {
              "project_path": {
                  "type": "string",
                  "description": "Path to the Godot project directory or its project.godot file.",
              },
              "settings": {
                  "type": "array",
                  "description": "List of setting updates. Each item must include `name` plus exactly one of `value` or `value_godot`.",
                  "items": {
                      "type": "object",
                      "properties": {
                          "name": {
                              "type": "string",
                              "description": "Project setting path, such as application/config/name or display/window/size/viewport_width.",
                          },
                          "value": {
                              "description": "JSON-compatible value to save into ProjectSettings.",
                          },
                          "value_godot": {
                              "type": "string",
                              "description": "Optional raw Godot expression, such as Vector2i(1280, 720) or Color(1, 0, 0).",
                          },
                      },
                      "required": ["name"],
                      "additionalProperties": False,
                  },
                  "minItems": 1,
              },
              "godot_executable": {
                  "type": "string",
                  "description": "Optional explicit path to the Godot executable or .app bundle.",
              },
          },
          "required": ["project_path", "settings"],
          "additionalProperties": False,
      },
      handler=lambda args: self.controller.update_project_settings(
          project_path=args["project_path"],
          settings=args["settings"],
          godot_executable=args.get("godot_executable"),
      ),
  ),