VS Code MQTT Extension: Publish and Subscribe Without Leaving Your Editor

A VS Code MQTT extension removes the constant window-switching of IoT development: firmware in one window, a desktop client in another, a terminal somewhere behind both. In this guide you will set up MQTT inside Visual Studio Code with the ConnectMQ extension, organize test payloads as files in your repository, and add workspace tasks that run repeatable CLI checks. Everything is demonstrated against the free public broker broker.connectmq.com.

Why Bring MQTT into the Editor

When you change a topic name in code, you want to see the effect immediately. When you fix a JSON field, you want to publish a test payload that exercises the fix. Doing this inside the editor has concrete benefits:

• Shorter feedback loop. Edit, flash or restart, and watch the topic in a panel beside the code.
• Payloads live with the code. Test messages become versioned files that teammates can reuse and review.
• Fewer tools to install. New team members get the extension and the workspace tasks, and they are ready.
• Consistent connection settings. Everyone tests against the same broker settings, which avoids "works on my machine" topic mistakes.

Installing the ConnectMQ VS Code Extension

1. Open the Extensions view (Ctrl+Shift+X, or Cmd+Shift+X on macOS).
2. Search for ConnectMQ and install the official extension.
3. Open the extension from its icon or through the Command Palette (Ctrl+Shift+P) by typing the extension name.

The extension lets you connect to MQTT brokers, subscribe to topics and publish test payloads without leaving VS Code. It works with any standard MQTT broker. Exact labels may change between versions; the extension's page in the Marketplace is the reference for the current UI.

Connecting to a Broker

Create a connection with these values for the public test broker:

Choose a unique topic prefix for your tests, such as connectmq/demo/7hq2/. The public area is readable by everyone, so never publish secrets or real customer data there. Public limits are 64 KB per message, 10 messages per second per client, 10 subscriptions per client and up to 8 topic levels.

Subscribe and Publish from the VS Code MQTT Extension

With the connection open:

1. Subscribe to connectmq/demo/7hq2/# to see everything under your prefix.
2. Publish a test message to connectmq/demo/7hq2/device1/cmd with payload {"action": "blink", "times": 3}.
3. Confirm it arrives in your subscription view, then point your device or service at the same topics.

Typical debugging moves that become quick inside the editor:

• Topic typo hunt. Subscribe to the parent with # and compare the topics that actually arrive with the strings in your code.
• Retained state check. Reconnect and see which topics show a value immediately; those are retained.
• Command testing. Publish the exact command your app would send, and watch the device's response topic.

Keep Test Payloads as Files in Your Repo

Whatever client you publish from, store canonical test messages in the repository. A simple layout:

mqtt/
  payloads/
    cmd-blink.json
    cmd-reboot.json
    telemetry-normal.json
    telemetry-out-of-range.json
  README.md

Example mqtt/payloads/telemetry-out-of-range.json:

{
  "deviceId": "device1",
  "temperature": 142.7,
  "humidity": -3,
  "ts": 1760600000000
}

Edge-case payloads like this one (impossible values, missing fields, wrong types) are the ones you will need when testing validation in your backend. Keeping them as files makes them reviewable, and VS Code validates JSON syntax as you type.

Add Workspace Tasks for Repeatable CLI Checks

An extension is ideal for interactive work. For repeatable checks, VS Code tasks that wrap mosquitto_pub and mosquitto_sub complement it well and run in the integrated terminal. Create .vscode/tasks.json:

{
  "version": "2.0.0",
  "inputs": [
    {
      "id": "payloadFile",
      "type": "pickString",
      "description": "Payload to publish",
      "options": [
        "mqtt/payloads/cmd-blink.json",
        "mqtt/payloads/telemetry-normal.json",
        "mqtt/payloads/telemetry-out-of-range.json"
      ]
    }
  ],
  "tasks": [
    {
      "label": "MQTT: watch demo topics",
      "type": "shell",
      "command": "mosquitto_sub -h broker.connectmq.com -p 1883 -i vscode-watch-7hq2 -t 'connectmq/demo/7hq2/#' -v",
      "isBackground": true,
      "problemMatcher": []
    },
    {
      "label": "MQTT: publish payload file",
      "type": "shell",
      "command": "mosquitto_pub -h broker.connectmq.com -p 1883 -i vscode-pub-7hq2 -t connectmq/demo/7hq2/device1/telemetry -q 1 -f ${input:payloadFile}",
      "problemMatcher": []
    },
    {
      "label": "MQTT: wait for one telemetry message",
      "type": "shell",
      "command": "mosquitto_sub -h broker.connectmq.com -p 1883 -i vscode-check-7hq2 -t connectmq/demo/7hq2/device1/telemetry -C 1 -W 15",
      "problemMatcher": []
    }
  ]
}

Run them from Terminal > Run Task. The pickString input lets you choose which payload file to send, and -f publishes the file content as the message. The last task exits with an error if nothing arrives within 15 seconds, which is a handy smoke test after flashing firmware. If you need more variations, see mosquitto_pub and mosquitto_sub examples. These tasks need the Mosquitto clients installed; MQTT CLI tools compares alternatives if you prefer another command-line client.

A Practical Firmware Workflow

Here is how this fits together when developing an ESP32 device in VS Code with PlatformIO:

1. Start the "watch demo topics" task (or subscribe in the extension).
2. Build and upload the firmware; open the serial monitor in another panel.
3. Watch the device's first telemetry and its retained status appear.
4. Publish cmd-blink.json to the command topic and watch the LED and the serial log.
5. Publish telemetry-out-of-range.json to the telemetry topic to check how your backend handles bad data.

All five steps happen without leaving the editor. For the device side, the ESP32 MQTT tutorial gives you firmware that matches this topic layout.

Handling Credentials Safely in a Workspace

Never commit broker passwords in tasks.json or payload files. Two safer patterns:

• Use environment variables in tasks: -u $MQTT_USER -P $MQTT_PASS (on Windows PowerShell, $env:MQTT_USER), and set them in your shell profile or a local .env file excluded by .gitignore.
• Keep a Mosquitto client config file outside the repo (~/.config/mosquitto_pub) containing the -u and -P lines.

For a private broker on ConnectMQ, the portal generates the username, password and client ID when you create the broker, and client IDs are bound to those credentials, so use the issued ID in both the extension and the tasks. MQTT security best practices covers credential handling for devices and teams.

Editor, Desktop or Browser?

Moving Beyond the Public Broker

The free public MQTT broker is ideal for trying the extension, but team development and real devices need a private, authenticated broker. A managed MQTT broker gives every developer and device its own credentials over TLS, without you operating servers. When you are ready to write application code, the MQTT client libraries overview shows the equivalent publish and subscribe calls in each major language.

Get Started with ConnectMQ

Install the ConnectMQ VS Code extension, then create a private broker at app.connectmq.com on the free Serverless plan, no credit card required. Paste the generated credentials into a new connection and you can test real device traffic from your editor in minutes.

Frequently Asked Questions

Is there an MQTT client built into VS Code?

No. VS Code has no built-in MQTT support, so you add it with an extension such as the one described here, or with tasks that run command-line clients in the integrated terminal.

Does the ConnectMQ VS Code extension work with other brokers?

Yes. It connects to standard MQTT brokers, and it is a natural fit for brokers created in the portal.

Can I run MQTT tests automatically from VS Code?

Yes. Workspace tasks can publish payload files and wait for expected messages with mosquitto_sub -C 1 -W 15, which fails the task if nothing arrives in time.

Should I commit tasks.json with broker settings?

Commit tasks that use the public broker or environment variables, but never commit passwords. Keep private credentials in environment variables or local config files excluded from git.