Control Hardware with Plain English: The Complete Guide to mcp2mqtt

From “Turn the light to 70 %” to a PWM signal on pin 9 in 200 ms—no code, no cloud lock-in

Introduction: Why mcp2mqtt Exists

Have you ever wished you could say, “Dim the desk lamp to 30 %” and watch it happen—without reaching for an app, writing a REST client, or soldering new firmware?
mcp2mqtt is the missing bridge between large language models (LLMs) and the real world. It takes natural-language instructions, translates them into MQTT messages, and forwards them to any serial device that speaks plain ASCII.

In this guide you will learn:

1. What mcp2mqtt is (and what it is not)
2. How data flows from Claude Desktop to your microcontroller
3. Installation on Windows, macOS, Ubuntu, and Raspberry Pi
4. A minimal YAML file that controls a PWM LED in four lines
5. Troubleshooting steps that solve 90 % of first-day issues
6. Real-world examples: temperature sensor, multi-device lighting, and fan control

The article is based entirely on the official README and my own first-hand testing; no external sources were used.

1. What Exactly Is mcp2mqtt?

Bottom line:
mcp2mqtt = MCP adapter + MQTT client + serial bridge.

2. Architecture: A Three-Hop Journey

1. User → “Set the red LED to 80 %”
2. LLM client → MCP tool call set_pwm{"value":80}
3. mcp2mqtt → MQTT publish mcp/pwm → MCU receives PWM 80\n
4. MCU → duty cycle changed → replies OK → mcp2mqtt → MCP response
5. LLM → “Red LED is now at 80 % brightness.”

3. Prerequisites Checklist

4. Installation in Under 5 Minutes

Windows

curl -O https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install.py
python install.py

macOS

curl -O https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install_macos.py
python3 install_macos.py

Ubuntu / Raspberry Pi OS

curl -O https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install_ubuntu.py
python3 install_ubuntu.py

The script will:

• Check Python version
• Install pyserial, mcp, and uv if missing
• Drop a starter config.yaml
• Auto-patch Claude Desktop’s MCP JSON when found

5. Where Should I Put My config.yaml?

Create the directory if it does not exist:

# Linux/macOS
mkdir -p ~/.mcp2mqtt

# Windows PowerShell
mkdir "$env:USERPROFILE\.mcp2mqtt"

The server searches in that order and uses the first file it finds.

6. A 20-Line YAML File That Actually Works

# config.yaml
serial:
  port: auto-detect        # or "COM11", "/dev/ttyUSB0"
  baud_rate: 115200

mqtt:
  broker: localhost
  port: 1883
  client_id: mcp2mqtt_desk
  username: ""
  password: ""
  topics:
    command:
      publish: "mcp/command"
      subscribe: "mcp/response"
    status:
      publish: "mcp/status"
      subscribe: "mcp/control"

commands:
  set_pwm:
    command: "PWM {frequency}\n"
    need_parse: false
    data_type: ascii
    prompts:
      - "Set PWM to {value}%"
      - "Dim to {value} percent"
    mqtt_topic: "mcp/pwm"
    response_topic: "mcp/pwm/response"

7. Connecting Claude Desktop

Edit Claude Desktop’s JSON file:

Windows
%APPDATA%\Claude\claude_desktop_config.json

macOS
~/Library/Application Support/Claude/claude_desktop_config.json

Linux / Flatpak
~/.var/app/com.claudeai.Claude/config/Claude/claude_desktop_config.json

Add the server block:

{
  "mcpServers": {
    "mcp2mqtt": {
      "command": "uvx",
      "args": ["mcp2mqtt"]
    }
  }
}

For local development use the absolute path:

{
  "mcpServers": {
    "mcp2mqtt": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/Users/you/projects/mcp2mqtt",
        "run",
        "mcp2mqtt"
      ]
    }
  }
}

Restart Claude Desktop. Type:
“Set PWM to 45 percent.”
If the serial LED fades, you are done.

8. Real-World Examples

8.1 Single LED PWM

YAML already shown above. Hardware: ESP32 + MOSFET + 12 V LED strip.

8.2 Temperature Sensor with Parsing

commands:
  get_temperature:
    command: "GET_TEMP\n"
    need_parse: true
    data_type: ascii
    prompts:
      - "What is the temperature?"
      - "Read sensor"

MCU response:
OK TEMP=22.8

Claude will reply:
“The sensor reports 22.8 °C.”

8.3 Multi-Device Lighting

Split topics per room:

commands:
  set_living_room:
    command: "LR_PWM {value}\n"
    mqtt_topic: "mcp/living_room"
    prompts:
      - "Dim living room to {value}%"
  set_bedroom:
    command: "BR_PWM {value}\n"
    mqtt_topic: "mcp/bedroom"
    prompts:
      - "Set bedroom light to {value}%"

9. Troubleshooting Quick-Start

10. FAQ: Users Ask, We Answer

Q1: Can I run mcp2mqtt on a headless Raspberry Pi?
A: Yes. Install via the Ubuntu script, then run as a systemd service:

sudo nano /etc/systemd/system/mcp2mqtt.service
# paste the sample unit file from docs/
sudo systemctl enable --now mcp2mqtt

Q2: Is TLS supported for MQTT?
A: The underlying paho-mqtt supports TLS. Add tls: true and certs to the YAML; syntax identical to standard paho examples.

Q3: How do I add a new command without restarting Claude?
A: Save the YAML; mcp2mqtt watches the file and hot-reloads. Claude picks up the new tool on the next prompt.

Q4: Can multiple AI clients talk to one mcp2mqtt instance?
A: Yes. Each client maintains its own MCP session; mcp2mqtt is stateless.

Q5: Is Windows COM port auto-detection reliable?
A: For single-adapter setups it works 100 %. With multiple adapters, hard-code the COM number.

11. Installing from Source (Optional)

git clone https://github.com/mcp2everything/mcp2mqtt.git
cd mcp2mqtt
uv venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install --editable .

Run:

uv run src/mcp2mqtt/server.py

12. Running Tests

uv pytest tests/

All tests must pass before opening a pull request.

13. Roadmap & Contribution

We welcome:

• New YAML command templates
• Additional language prompts
• CI improvements

Open an issue first for large changes, then submit a PR.

14. License & Credits

• MIT License
• Thanks to the Claude team for MCP
• Thanks to pySerial for rock-solid UART handling

15. Next Steps

1. Flash an ESP32 with the example firmware
2. Copy the YAML snippets above
3. Say, “Set the fan to low speed” and watch the blades spin

When you build something fun—smart greenhouse, voice-controlled coffee machine, or a 3D-printer enclosure—share your YAML on GitHub Discussions so the community can say, “Hey, that’s exactly what I needed.”

Happy building!