godot_update_project_settings

Modify Godot project configuration values directly through the engine. Update settings like window size, application name, or display properties by specifying paths and values, then save changes to the project file.

Instructions

Update one or more ProjectSettings values and save them back to the Godot project through Godot itself.

Input Schema

TableJSON Schema

Name	Required	Description
`project_path`	Yes	Path to the Godot project directory or its project.godot file.
`settings`	Yes	List of setting updates. Each item must include `name` plus exactly one of `value` or `value_godot`.
`godot_executable`	No	Optional explicit path to the Godot executable or .app bundle.

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"),
    ),
),

Godot MCP