MQTT Client

Publish and subscribe MQTT messages directly from .mqtt files in Visual Studio Code.

File Formats

.mqtt files support two formats:

Both formats support variables, and existing legacy files can be converted to YAML using the built-in command.

Legacy Format

Write blocks in a .mqtt file. Each block starts on a line beginning with a unique string that starts with #. The block-starting line must not contain any additional characters, including spaces.

Connection block

Write connection settings in a block starting with # %%. Click Connect displayed above # %% to connect to the broker.

Warning: Avoid writing passwords in plain text, as .mqtt files may be committed to version control. Use ${secret:<key>} instead to keep credentials out of the file.

# %%
url: mqtt://broker:1883
user: user
password: ${secret:my-broker}

Subscription block

Write one topic per line in a block starting with # $$. Click Subscribe all or Subscribe to open a subscription tab and start receiving messages.

# $$
foo
bar/#

Publish block

Write one block starting with # ## for each message you want to publish. Write the publish settings, leave a blank line, then write the message payload. A line matching another block marker (e.g. # %%) inside the payload is not supported — it will be treated as the start of a new block. Click Publish message displayed above # ## to publish.

# ## Publish 'message'
topic: foo
qos: 0
retain: false

message


# ## Publish '{ "message": "hello" }'
topic: bar
qos: 1
retain: true

{
    "message": "hello"
}

Variables

Define variables above all blocks, one per line, in the form name=value. Reference a variable with {{name}}. If the variable is not defined, it is treated as a literal string. To use a {{...}} literal that would otherwise match a defined variable, wrap it in an extra layer: {{{{name}}}}.

Variables can be used in:

• Other variable values (only variables defined above can be referenced)
• Setting values (key: value lines in connection and publish blocks)
• Topics in Subscription blocks
• Payloads in Publish blocks

host=broker
TopicLevel1=foo
TOPIC_FOO={{TopicLevel1}}/foo
message=Hello, world!

# %%
url: mqtt://{{host}}:1883

# $$
{{TopicLevel1}}/#

# ## Publish '{ "message": "Hello, world!" }'
topic: {{TopicLevel1}}/bar

{
    "message": "{{message}}"
}

# ## Publish '{{message}}'
topic: {{TOPIC_FOO}}

{{{{message}}}}

Comments

Any line that doesn't follow the rules of a block is ignored and can be used as a comment. Comments are not supported inside subscription topics or message payloads.

comment
host=broker
comment
message=Hello, world!

# %%
comment
url: mqtt://{{host}}:1883
comment

# $$
{{TopicLevel1}}/#

# ##
comment

topic: {{TopicLevel1}}/bar
comment

{
    "message": "{{message}}"
}
not a comment

YAML Format

YAML format provides a more structured alternative. A file is detected as YAML format when its first non-blank, non-comment line is one of: variables:, connection:, subscriptions:, or publish:.

Structure

variables:
  host: broker.example.com
  topic1: sensors/temperature

connection:
  url: "mqtt://{{host}}:1883"
  username: user
  password: "${secret:my-broker}"
  clientId: my-client
  ca: certs/ca.crt
  reconnectPeriod: 5000

subscriptions:
  - "{{topic1}}"
  - topic: sensors/humidity
    qos: 1

publish:
  - topic: sensors/update
    qos: 0
    retain: false
    payload: '{"status": "ok"}'

  - name: Multiline JSON
    topic: sensors/data
    qos: 1
    payload: |
      {
        "temperature": 25,
        "unit": "celsius"
      }

connection

Warning: Avoid writing passwords in plain text, as .mqtt files may be committed to version control. Use ${secret:<key>} instead to keep credentials out of the file.

subscriptions

Each item can be a plain string or an object with topic and optional qos:

subscriptions:
  - sensors/temperature      # qos defaults to 0
  - topic: sensors/humidity
    qos: 1

publish

Payload formats

The payload field must be a string. The following formats are supported:

Note: Writing payload: as a YAML mapping (without quotes or |) will result in an editor warning and the message will not be sent.

Variables

Variables work the same way as in the legacy format. Use {{variableName}} to reference a variable.

variables:
  host: broker.example.com

connection:
  url: "mqtt://{{host}}:1883"

YAML Anchors and Merge Keys

Standard YAML anchors (&), aliases (*), and merge keys (<<:) are supported. This is useful for sharing settings across multiple publish entries.

publish:
  - &base
    topic: sensors/temperature
    qos: 1
    retain: false
    payload: "hello"

  - <<: *base
    topic: sensors/humidity
    payload: "world"

The second entry inherits qos and retain from base, and overrides topic and payload.

Converting Legacy Format to YAML

Use the MQTT: Convert to YAML command to convert a legacy .mqtt file to YAML format.

1. Open the .mqtt file to convert
2. Run the command via:
   • Right-click in the editor → MQTT: Convert to YAML
   • Command Palette (Ctrl+Shift+P / Cmd+Shift+P) → MQTT: Convert to YAML
3. A new file is created in the same directory with .yaml inserted before the extension (e.g., config.mqtt → config.yaml.mqtt)
4. The new file opens automatically

Notes:

• The original file is not modified or deleted
• If the file is already in YAML format, a message is shown and no file is created

Example

Before (config.mqtt):

host=broker.example.com

# %%
url: mqtt://{{host}}:1883
user: myuser
password: ${secret:my-broker}

# $$
sensors/temperature
sensors/humidity

# ## Publish status
topic: sensors/status
qos: 1
retain: false

{"status": "ok"}

After (config.yaml.mqtt):

variables:
  host: broker.example.com

connection:
  url: "mqtt://{{host}}:1883"
  username: myuser
  password: "${secret:my-broker}"

subscriptions:
  - sensors/temperature
  - sensors/humidity

publish:
  - topic: sensors/status
    name: Publish status
    qos: 1
    retain: false
    payload: '{"status": "ok"}'

Secret Storage

Instead of writing passwords in plain text, you can store them in VSCode's SecretStorage (OS keychain) and reference them with ${secret:<key>}.

The <key> is a label to identify the stored secret — not the password itself. It can be any string that does not contain }. Choose a descriptive name like my-broker or work-mqtt.

Syntax

password: ${secret:my-broker}

When connecting, the extension resolves the secret using the following steps:

Commands

Legacy format example

# %%
url: mqtt://broker:1883
user: user
password: ${secret:my-broker}

YAML format example

connection:
  url: mqtt://broker:1883
  username: user
  password: "${secret:my-broker}"

Settings

Third-Party Notices

MQTT.js

Copyright (c) 2015-2016 MQTT.js contributors Released under the MIT license https://github.com/mqttjs/MQTT.js/blob/main/LICENSE.md

wait-queue

Copyright (c) 2017 flarestart Released under the MIT license https://github.com/flarestart/wait-queue/blob/master/LICENSE

js-yaml

Copyright (C) 2011-2015 by Vitaly Puzrin Released under the MIT license https://github.com/nodeca/js-yaml/blob/master/LICENSE