MCP2MQTT

You bridge physical devices with AI models using MCP communications over MQTT. This MCP server lets you control hardware with natural language through MQTT-enabled clients, while AI models contextually respond and drive device parameters in real time.

How to use

You connect an MCP client (such as Claude Desktop or Cline) to the MCP2MQTT server to send natural language commands that are translated into device actions. Practical use cases include adjusting PWM or LED states, querying device information, and receiving real-time status updates. The server publishes command topics and subscribes to response topics so you can orchestrate multiple devices and commands from a single interface. Start by ensuring your devices are connected to the MQTT broker, then configure an MCP client to point at the MCP2MQTT server and begin issuing commands like changing PWM, toggling LEDs, or requesting device info.

How to install

Prerequisites you need before installation are Python and the UV toolchain for running the MCP server, plus a working MQTT broker (such as Mosquitto or EMQ X). You also need a client capable of MCP protocol to test interactions.

# Windows
python install.py

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

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

If you prefer manual dependency setup, ensure the uv toolchain is installed, then install Python dependencies and any required client components. The setup will prepare a default configuration and integrate with Claude Desktop if installed.

Additional configuration and run steps

Configure your MCP client to connect to the MCP2MQTT server by providing an MCP2MQTT server entry. You can run the server in different modes depending on whether you want to point at a Python script or a locally registered MCP entry.

# Example: MQTT connection (consumer/producer topics are defined by the server)
mqtt:
  broker: "localhost"  # MQTT broker address
  port: 1883             # MQTT broker port
  client_id: "mcp2mqtt_client"
  username: "mqtt_user"
  password: "mqtt_password"
  keepalive: 60
  topics:
    command:
      publish: "mcp/command"
      subscribe: "mcp/response"
    status:
      publish: "mcp/status"
      subscribe: "mcp/control"

Run the MCP server

You can run the MCP server in stdio mode using a local uv runner. Choose the command variant that matches your preferred entry point.

# Run the server from a Python script (default setup)
uv run src/mcp2mqtt/server.py

# Run the server using a named MCP entry
uv run mcp2mqtt

To use a specific configuration file, append the --config option with the name of your config file (without the _config.yaml suffix). This lets you target different devices or environments in parallel.

uv run src/mcp2mqtt/server.py --config Pico
uv run mcp2mqtt --config Pico

Hardware and test setup

Connect your hardware over MQTT so the MCP server can publish commands and receive responses. You can also use a built-in responder to simulate a device for testing PWM, LED states, and device information.

# Start a device simulator to test PWM/LED/INFO interactions
python tests/responder.py

Troubleshooting and notes

If you encounter errors, check that your MQTT topics match the server’s command and response topics. Ensure the MCP client is configured to the correct server entry and that the selected config file exists and is readable.

Available commands on devices

You can control connected hardware with straightforward textual commands. For PWM, you send PWM values; for LED, you toggle on or off; you can also request device information.

PWM 100
PWM 0
PWM 50
LED on
LED off
INFO
`

Available tools

PWM Control

Adjusts the PWM output by sending PWM values through the MCP command channel and receiving confirmation responses.

LED Control

Turns the LED on or off and confirms the state with a response.

Device Info

Requests and returns information about the connected device.