This project sets up a real-time environmental monitoring system you can talk to in plain English. A XIAO ESP32-C3 reads temperature, humidity, and pressure from a BME280 sensor and publishes the data over MQTT to a Mosquitto broker running on your PC. A custom Model Context Protocol (MCP) server bridges the broker to Claude Desktop, so you can ask Claude questions about the live sensor data, or tell it to do things like turn an LED on and off based on what it sees.

This works well as a natural-language environmental assistant for indoor spaces like bedrooms, study areas, server closets, or small grow setups. Instead of staring at a dashboard full of numbers, you just ask Claude what's going on and get a proper answer with context. It can also trigger physical actions, like switching on an indicator LED when a sensor threshold is crossed. Everything runs locally on your network with no external API keys, and you can have it built in about one to two hours on any modern laptop.

Gather everything below before you start.

You'll be working with three project files: the Arduino sketch on the ESP32, the Node.js MCP server on your PC, and the Claude Desktop config file. All three are listed in full in the Code section below.

The XIAO ESP32-C3 is the main controller. It's a compact RISC-V microcontroller with built-in 2.4 GHz Wi-Fi, which makes it a good fit for small wireless IoT nodes. In this project it reads the BME280 over I2C, connects to Wi-Fi, and uses MQTT to publish sensor readings to the broker. It also subscribes to a command topic so it can react to instructions from Claude in real time, like turning the LED on when told to.

The BME280 is a combined temperature, humidity, and barometric pressure sensor from Bosch. It talks over I2C, so it only needs two data lines (SDA and SCL) plus power and ground. Compared to a DHT11 or DHT22, it gives faster updates, finer resolution, and throws in a pressure reading. The XIAO polls it every five seconds and packs the readings into a small JSON payload.

Mosquitto is a lightweight open-source MQTT broker. MQTT (Message Queuing Telemetry Transport) is a publish-subscribe protocol built for constrained devices and unreliable networks. Devices that produce data publish messages to named channels called topics; devices that consume data subscribe to those topics. The broker sits in the middle, receives every published message, and forwards it to whoever's currently subscribed. That means the publisher and subscriber never have to know about each other or even be online at the same time. They just need to share the same broker.

The Model Context Protocol (MCP) is an open standard that lets an AI assistant call external tools through a structured interface. The MCP server here is a small Node.js program that connects to Mosquitto as an MQTT client, caches the latest value and a rolling history for every topic it's subscribed to, and exposes that data to Claude as a set of callable tools. When Claude needs to answer a question about a sensor, it calls one of these tools; when it needs to control the LED, it calls a different tool that publishes back to the broker. The MCP server is what turns Claude from a chatbot into something that can actually see and touch your hardware.

Claude Desktop is the AI client you talk to. Once it's configured with the MCP server, it can read live sensor data, interpret the values in plain language, generate charts from history, and decide when to send control commands. Since the AI runs through Claude Desktop, you don't need API keys, paid subscriptions, or cloud services. The whole thing runs on your machine and your local network.

The LED is the physical output. It's wired through a current-limiting resistor to GPIO 10 (pin D10) on the XIAO. When Claude publishes "ON" or "OFF" to the LED command topic, the XIAO flips the pin accordingly.

Wire the components to the XIAO ESP32-C3 using the tables below. Everything sits on the same breadboard with a shared ground rail.

1. Place the BME280 module and the LED on the breadboard.
2. Connect the BME280 VCC to the 3.3V pin of the XIAO. Important: do not use 5V.
3. Connect the BME280 GND to the breadboard's ground rail, then run one wire from that rail to a GND pin on the XIAO. The LED's cathode also connects to this same rail.
4. Connect the BME280 SDA to D4 (GPIO 6) and SCL to D5 (GPIO 7).
5. Connect the LED's long leg (anode) through a 220 Ω resistor to D10 (GPIO 10). Connect the short leg (cathode) to the shared ground rail.
6. Plug the XIAO into the host computer via a data-capable USB-C cable.

The build goes in six steps, each with a checkpoint to confirm that part of the system works before moving on. Don't skip the checkpoints. Debugging is way easier when you know exactly which layer is failing.

1. Turn on a mobile hotspot in 2.4 GHz mode.
2. Make the hotspot name (SSID) simple. If your device name has an apostrophe in it (like "User's iPhone"), rename the device first. The apostrophe the iPhone broadcasts is a curly Unicode character that breaks Arduino string literals.
3. Connect the host PC to the hotspot.
4. Open Command Prompt and run ipconfig. Note the Wi-Fi adapter's IPv4 address. On an iPhone hotspot this is usually 172.20.10.X. This is the MQTT broker address and you'll need it in a few places below.

1. Install Arduino IDE from arduino.cc/en/software.
2. Open File → Preferences. In Additional Board Manager URLs, add:
   urlCopy

   https://espressif.github.io/arduino-esp32/package_esp32_index.json

3. Open Tools → Board → Boards Manager, search "esp32", and install esp32 by Espressif Systems version 3.0 or newer.
4. Select Tools → Board → esp32 → XIAO_ESP32C3.
5. In Tools, set USB CDC On Boot to Enabled. Without this the Serial Monitor stays blank over USB-C.
6. Open Sketch → Include Library → Manage Libraries and install:
   • Adafruit BME280 Library
   • Adafruit Unified Sensor (usually auto-prompted as a dependency)
   • PubSubClient by Nick O'Leary

1. Download Mosquitto from mosquitto.org/download and run the Windows 64-bit installer with default options. It installs to C:\Program Files\mosquitto\ and registers a Windows service that starts on boot.
2. Open Notepad as Administrator, then File → Open. In the file-type dropdown choose All Files (*.*) and open C:\Program Files\mosquitto\mosquitto.conf.
3. Scroll to the bottom of the file and add the two lines below. The first lets other devices on the network connect; the second allows connections without a password (fine for a local demo).
   mosquitto.confCopy

   listener 1883 0.0.0.0
   allow_anonymous true

4. Save and close the file.
5. Open Command Prompt as Administrator and allow port 1883 through Windows Firewall:
   cmd (admin)Copy

   netsh advfirewall firewall add rule name="Mosquitto MQTT" dir=in action=allow protocol=TCP localport=1883

6. Restart Mosquitto so it picks up the new config. If it's running as a service, restart it with net stop mosquitto then net start mosquitto in admin Command Prompt. Otherwise launch it manually:
   cmd (admin)Copy

   cd "C:\Program Files\mosquitto"
   mosquitto -c mosquitto.conf -v

7. Check that Mosquitto is listening:
   cmdCopy

   netstat -an | findstr :1883

   You should see something like TCP 0.0.0.0:1883 0.0.0.0:0 LISTENING.

1. Install Node.js LTS from nodejs.org with default options. After installing, open a fresh Command Prompt and check:
   cmdCopy

   node -v
   npm -v

   Both commands should return a version number.
2. Create the MCP server project:
   cmdCopy

   cd %USERPROFILE%
   mkdir mqtt-mcp-server
   cd mqtt-mcp-server
   npm init -y
   npm install @modelcontextprotocol/sdk mqtt dotenv zod

3. Open package.json in Notepad using the command notepad package.json, and change "type": "commonjs" to "type": "module". The MCP server uses ES module imports and won't run otherwise.
4. Create index.js in the same folder and paste in the source from the Code section below. Save and close.
5. Note the project path. You'll need it for the Claude config:
   cmdCopy

   cd

   It should show something like C:\Users\YOURNAME\mqtt-mcp-server.

1. Install Claude Desktop. Either the Microsoft Store version or the direct installer from claude.ai/download works.
2. Sign in to Claude Desktop with your account.
3. Create the config file. In Command Prompt:
   cmdCopy

   mkdir "%APPDATA%\Claude"
   notepad "%APPDATA%\Claude\claude_desktop_config.json"

   Click Yes when Notepad asks to create the file. Paste in the JSON from the Code section, replacing the placeholders with your actual Windows username and the broker IP from Step 1.
4. Save the file using File → Save As, with Save as type set to All Files (*.*). Otherwise Notepad quietly saves it as claude_desktop_config.json.txt and Claude won't find it.
5. Fully quit Claude Desktop (right-click the system tray icon and choose Quit). Reopen it from the Start menu. The MCP server launches automatically.
6. Click the tools icon in the chat input area. You should see the mqtt server listed with 6 tools: read_topic, write_topic, subscribe_topic, unsubscribe_topic, list_topics, and read_history.

1. Open the Arduino sketch from the Code section in Arduino IDE.
2. At the top of the file, edit three constants:
   • WIFI_SSID: your WiFi's name
   • WIFI_PASSWORD: your WiFi's password
   • MQTT_BROKER: the host PC's IP address from Step 1
3. Plug in the XIAO and select the right COM port under Tools → Port.
4. Click Upload. After uploading, open Tools → Serial Monitor at 115200 baud and press the reset button on the XIAO.

Copy each file below into the right location as described in the Software Setup section. The MCP server code is the same for everyone. Only the credentials and paths in the Arduino sketch and the Claude config need to change.

Place this in C:\Users\YOURNAME\mqtt-mcp-server\index.js. Remember to also set "type": "module" in the adjacent package.json.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import mqtt from "mqtt";
import dotenv from "dotenv";
dotenv.config();

// MQTT topics to auto-subscribe to on startup
const FEEDS = [
  "home/sensor/bme280",
  "home/sensor/bme280/led",
  "home/sensor/bme280/led/status",
];

const MAX_HISTORY = 100;

// ===== Always-on automation rules (independent of Claude) =====
// Each rule watches a topic and publishes a command when a threshold is crossed.
// Add more rules to the array as needed.
const AUTO_RULES = [
  {
    topic: "home/sensor/bme280",
    field: "temperature",
    threshold: 30,
    ledTopic: "home/sensor/bme280/led"
  }
];

// Track the last command published per LED topic, so we don't spam
// the broker with duplicate ON/ON/ON or OFF/OFF/OFF messages.
const lastAutoCommand = {};

const mqttOptions = {
  host: process.env.MQTT_HOST,
  port: parseInt(process.env.MQTT_PORT || "1883"),
};
if (process.env.MQTT_USERNAME) mqttOptions.username = process.env.MQTT_USERNAME;
if (process.env.MQTT_PASSWORD) mqttOptions.password = process.env.MQTT_PASSWORD;

const client = mqtt.connect(mqttOptions);

const topicValues = {};
const topicHistory = {};

client.on("connect", () => {
  FEEDS.forEach(feed => {
    client.subscribe(feed, err => {
      if (err) console.error(`Failed: ${feed} -- ${err.message}`);
      else console.error(`Subscribed: ${feed}`);
    });
  });
});

// Cache every incoming message, push to history, AND evaluate automation rules
client.on("message", (topic, message) => {
  const entry = { value: message.toString(), timestamp: new Date().toISOString() };
  topicValues[topic] = entry;
  if (!topicHistory[topic]) topicHistory[topic] = [];
  topicHistory[topic].push(entry);
  if (topicHistory[topic].length > MAX_HISTORY) topicHistory[topic].shift();

  // Evaluate automation rules for this topic
  AUTO_RULES.forEach(rule => {
    if (topic !== rule.topic) return;
    try {
      const data = JSON.parse(message.toString());
      const value = data[rule.field];
      if (typeof value !== "number") return;
      const desired = value > rule.threshold ? "ON" : "OFF";
      if (lastAutoCommand[rule.ledTopic] !== desired) {
        client.publish(rule.ledTopic, desired);
        lastAutoCommand[rule.ledTopic] = desired;
        console.error(`[AUTO] ${rule.field}=${value} threshold=${rule.threshold} -> LED ${desired}`);
      }
    } catch (e) {
      // not JSON or parse failed, skip silently
    }
  });
});

function publishToTopic(topic, value) {
  return new Promise((resolve, reject) =>
    client.publish(topic, String(value), { qos: 1 },
      err => err ? reject(err) : resolve()));
}

const server = new McpServer({ name: "mqtt-generic", version: "1.2.0" });

server.tool("read_topic",
  { topic: z.string().describe("Full MQTT topic, e.g. home/sensor/bme280") },
  async ({ topic }) => {
    const data = topicValues[topic];
    if (!data) return { content: [{ type: "text",
      text: `No data yet for "${topic}". Device may not have published.` }] };
    return { content: [{ type: "text",
      text: `Topic: ${topic}\nValue: ${data.value}\nUpdated: ${data.timestamp}` }] };
  }
);

server.tool("write_topic",
  { topic: z.string().describe("Topic to publish to"),
    value: z.string().describe("Value to send e.g. 1, 0, ON, OFF, 75") },
  async ({ topic, value }) => {
    try {
      await publishToTopic(topic, value);
      return { content: [{ type: "text", text: `Published "${value}" to "${topic}"` }] };
    } catch (err) {
      return { content: [{ type: "text", text: `Publish failed: ${err.message}` }] };
    }
  }
);

server.tool("subscribe_topic",
  { topic: z.string().describe("New topic to start listening to") },
  async ({ topic }) => new Promise(res =>
    client.subscribe(topic, err => res({ content: [{ type: "text",
      text: err ? `Error: ${err.message}` : `Now subscribed to "${topic}"` }] }))
  )
);

server.tool("unsubscribe_topic",
  { topic: z.string().describe("Topic to stop listening to") },
  async ({ topic }) => new Promise(res =>
    client.unsubscribe(topic, err => {
      if (!err) { delete topicValues[topic]; delete topicHistory[topic]; }
      res({ content: [{ type: "text",
        text: err ? `Error: ${err.message}` : `Unsubscribed from "${topic}"` }] });
    })
  )
);

server.tool("list_topics", {}, async () => {
  const keys = Object.keys(topicValues);
  if (!keys.length) return { content: [{ type: "text", text: "No topic data received yet." }] };
  const list = keys.map((t, i) => {
    const hist = topicHistory[t] ? topicHistory[t].length : 0;
    return `${i+1}. ${t}\n   Value: ${topicValues[t].value}\n   At: ${topicValues[t].timestamp}\n   History size: ${hist}`;
  }).join("\n\n");
  return { content: [{ type: "text", text: `Active topics (${keys.length} total):\n\n${list}` }] };
});

server.tool("read_history",
  { topic: z.string().describe("Topic to get history for"),
    count: z.number().optional().describe("How many recent readings (default 20, max 100)") },
  async ({ topic, count }) => {
    const history = topicHistory[topic];
    if (!history || history.length === 0) {
      return { content: [{ type: "text",
        text: `No history yet for "${topic}". Wait a bit for readings to accumulate.` }] };
    }
    const n = Math.min(count || 20, history.length);
    const slice = history.slice(-n);
    return { content: [{ type: "text",
      text: `Last ${n} of ${history.length} readings for ${topic}:\n${JSON.stringify(slice, null, 2)}` }] };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Place this at %APPDATA%\Claude\claude_desktop_config.json. Replace YOURNAME with your Windows username and put your host PC's IP into MQTT_HOST.

{
  "mcpServers": {
    "mqtt": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\Users\\YOURNAME\\mqtt-mcp-server\\index.js"],
      "env": {
        "MQTT_HOST": "XXXXXXXXXXX",
        "MQTT_PORT": "1883"
      }
    }
  }
}

Here's what each part of the system does. Read through this after uploading so you understand how data flows from the sensor all the way to Claude.

setup()

loop()

mqttCallback()

setLed()

connectWiFi() and connectMQTT()

Every message from the XIAO triggers two parallel paths inside the MCP server: one for AI-driven interaction (Claude) and one for always-on rule-based automation. Both end up controlling the same LED topic.

1. The XIAO ESP32-C3 boots, connects to Wi-Fi, initializes the BME280, and connects to the Mosquitto broker.
2. Every 5 seconds the XIAO reads the sensor, filters out garbage values, and publishes a JSON payload to home/sensor/bme280.
3. Mosquitto receives the payload and forwards it to every subscriber.
4. The MCP server, as a subscriber, caches the latest value and appends it to a rolling history buffer.
5. The MCP server also checks every entry in the AUTO_RULES array against the new reading. If a threshold has been crossed since the last reading, it publishes the matching LED command directly to the broker. This happens whether Claude is being used or not.
6. Separately, when you ask Claude a question, it picks which tool to call. For a status query it calls read_topic; for a chart it calls read_history; for manual control it calls write_topic.
7. Whenever a command lands on the LED topic, whether from an automation rule or from Claude, the XIAO's callback fires, flips the LED, and reports the new state back to the broker.
8. Claude reads the result of the tool call and answers you in natural language.

After uploading the sketch and configuring Claude, check each of these to make sure the system is actually working. Test from the bottom up: sensor first, then MQTT, then MCP, then Claude. It's a lot easier to debug when you know which layer is failing.

Open Arduino IDE → Serial Monitor at 115200 baud and press the reset button on the XIAO. You should see BME280 ready. followed by Published: lines every 5 seconds with reasonable values (around 25-30 °C, 40-80 % humidity, ~1010 hPa). If the readings are NaN, way out of range, or stuck on the same numbers for a long time, re-seat the BME280 wiring and check the USB cable for power issues.

Open a Command Prompt on the host PC and subscribe to the topic from the broker side. Replace 172.20.10.3 with your host PC's actual IP.

"C:\Program Files\mosquitto\mosquitto_sub.exe" -h 172.20.10.3 -t "home/sensor/bme280" -v

You should see live JSON payloads arriving every 5 seconds. This proves the messages are making it all the way from the ESP32 into Mosquitto.

If the ESP32 connects to Wi-Fi but fails MQTT with rc=-2, run this on the host PC:

netstat -an | findstr :1883

A line with 0.0.0.0:1883 ... LISTENING means Mosquitto is up. An extra line ending in ESTABLISHED with the XIAO's IP means the ESP32 is connected. If you only see LISTENING and no ESTABLISHED line, double-check that the MQTT_BROKER constant in the sketch matches the host PC's current IP exactly.

In Claude Desktop, click the tools icon in the chat input area. You should see the mqtt server with 6 tools listed. If it's missing, check the MCP server log at %APPDATA%\Claude\logs\mcp.log. The usual suspects are a wrong path in claude_desktop_config.json, missing "type": "module" in package.json, or the broker being unreachable when the MCP server started.

In a new Claude chat, ask: "What is the current temperature?" Claude should call read_topic, return a fresh reading that matches the latest Published: line in the Arduino Serial Monitor, and explain it in plain English. Allow the tool call when Claude asks for permission.

First verify the control path from the command line, which takes Claude out of the picture:

"C:\Program Files\mosquitto\mosquitto_pub.exe" -h 172.20.10.3 -t "home/sensor/bme280/led" -m "ON"
"C:\Program Files\mosquitto\mosquitto_pub.exe" -h 172.20.10.3 -t "home/sensor/bme280/led" -m "OFF"

The Serial Monitor should show Received on home/sensor/bme280/led: ON followed by LED set to ON, and the LED itself should respond. Once that works, try it through Claude by asking: "Turn on the LED by publishing ON to home/sensor/bme280/led."

Video Demonstration

• "What is the current temperature?"
• "What is the humidity right now?"
• "What is the air pressure?"
• "Show me all the active topics and their latest values."

Claude calls read_topic or list_topics and gives you the live reading.

• "Is the room too hot?"
• "Is the humidity comfortable?"
• "Is the air pressure normal for sea level?"
• "Explain the sensor readings."

Claude reads the values and actually reasons about what they mean instead of just giving you back a number.

• "Get the last 100 readings and chart temperature, humidity, and pressure over time."
• "Is the temperature trending up or down over the last few minutes?"
• "How fresh is the latest reading?"

Claude calls read_history, gets back an array of cached readings, and either summarizes the trend or drops a chart artifact straight into the chat.

• "Turn on the LED by publishing ON to home/sensor/bme280/led."
• "Check the temperature; if it's above 27°C, turn on the LED as a heat warning, otherwise turn it off."
• "Toggle the LED."

Claude calls write_topic, Mosquitto forwards the message to the XIAO, and the LED responds. That's the full monitoring-and-automation pipeline working end to end.

To figure out where the AI-driven automation actually breaks down, the system was tested under two conditions using the rule: "If temperature > 27°C, turn the LED ON; otherwise, turn it OFF." The goal was to see whether automation behaves the same when Claude is actively chatting versus when the chat is open but idle.

Test 1 — Chat open, Claude actively monitoring

Please monitor the temperature on home/sensor/bme280. Check the reading every
15 seconds for the next 2 minutes. If the temperature goes above 27°C, publish
"ON" to home/sensor/bme280/led. If it drops back below 27°C, publish "OFF".
Tell me each time you check and what you do.

Test 2 — Chat open, but Claude is idle

Test 3 — Always-on rule inside the MCP server

Summary of Findings

This project shows a full real-time environmental monitoring and automation system you can run with natural language. The XIAO ESP32-C3 reliably reads data from the BME280 and publishes it over MQTT to a Mosquitto broker, which covers the basic goal of capturing live sensor data and getting it onto the network. Bridging the broker to Claude through a custom MCP server lets you ask plain-English questions about the live data and get interpreted answers back, and to send plain-English commands that cause physical changes, closing the loop between sensing, reasoning, and action without any external API keys or cloud services. It's been tested on multiple laptops and across both wired and hotspot networks, so it's reproducible rather than tied to one specific machine.

• Add a soil moisture sensor to directly answer questions about plant watering.
• Swap the indicator LED for a relay module to switch real appliances like a fan or lamp.
• Move the broker to a cloud MQTT service (HiveMQ Cloud, EMQX Cloud) so you can access it from different networks instead of needing a shared local Wi-Fi.
• Persist sensor readings to a time-series database like SQLite or InfluxDB so the history survives MCP server restarts and supports longer-term analysis.
• Add more environmental sensors (CO₂, particulate matter, light) and expose each as its own MQTT topic.
• Build scheduled or threshold-based automations directly into the MCP server, with Claude as the natural-language configuration interface.
• Add a Telegram or web chat front-end so you can query the system from your phone instead of the desktop.

• Arduino IDE Documentation, arduino.cc
• Espressif Systems, ESP32-C3 Documentation
• Seeed Studio, XIAO ESP32-C3 Wiki
• Bosch Sensortec, BME280 Datasheet
• Eclipse Mosquitto, mosquitto.org
• Adafruit BME280 Library, github.com/adafruit/Adafruit_BME280_Library
• PubSubClient by Nick O'Leary, github.com/knolleary/pubsubclient
• Model Context Protocol, modelcontextprotocol.io
• MCP TypeScript SDK, github.com/modelcontextprotocol/typescript-sdk
• MQTT.js, github.com/mqttjs/MQTT.js
• Anthropic, Claude Desktop documentation
• Node.js Documentation, nodejs.org

• Keen Montilla
• Ben Sumauang