From fe9f19d9ed078db9eb3d82e2fb698c90dc9e6043 Mon Sep 17 00:00:00 2001
From: Jonathan Swoboda <154711427+swoboda1337@users.noreply.github.com>
Date: Sun, 15 Mar 2026 09:30:12 -0400
Subject: [PATCH] [mqtt] Fix ESP-IDF 6.0 compatibility for external MQTT
 component (#14822)

---
 esphome/components/mqtt/__init__.py | 8 +++++++-
 esphome/idf_component.yml           | 4 ++++
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/esphome/components/mqtt/__init__.py b/esphome/components/mqtt/__init__.py
index d110d7c160..817f99375e 100644
--- a/esphome/components/mqtt/__init__.py
+++ b/esphome/components/mqtt/__init__.py
@@ -3,7 +3,9 @@ from esphome.automation import Condition
 import esphome.codegen as cg
 from esphome.components import logger, socket
 from esphome.components.esp32 import (
+    add_idf_component,
     add_idf_sdkconfig_option,
+    idf_version,
     include_builtin_idf_component,
 )
 from esphome.config_helpers import filter_source_files_from_platform
@@ -351,7 +353,11 @@ async def to_code(config):
     if CORE.is_esp32:
         socket.require_wake_loop_threadsafe()
         # Re-enable ESP-IDF's mqtt component (excluded by default to save compile time)
-        include_builtin_idf_component("mqtt")
+        # IDF 6.0 moved esp-mqtt to an external component
+        if idf_version() >= cv.Version(6, 0, 0):
+            add_idf_component(name="espressif/mqtt", ref="1.0.0")
+        else:
+            include_builtin_idf_component("mqtt")
 
     cg.add_define("USE_MQTT")
     cg.add_global(mqtt_ns.using)
diff --git a/esphome/idf_component.yml b/esphome/idf_component.yml
index bb94de7e05..1e2d452919 100644
--- a/esphome/idf_component.yml
+++ b/esphome/idf_component.yml
@@ -37,5 +37,9 @@ dependencies:
     version: 0.3.2
     rules:
       - if: "target in [esp32, esp32s2, esp32s3, esp32c6, esp32p4]"
+  espressif/mqtt:
+    version: "1.0.0"
+    rules:
+      - if: "idf_version >=6.0.0"
   esp32async/asynctcp:
     version: 3.4.91