iflow-mcp-ezhuk-mqtt-mcp 0.3.0

A Model Context Protocol (MCP) server for MQTT

MQTT MCP Server

A lightweight Model Context Protocol (MCP) server that connects LLM agents to MQTT devices in a secure, standardized way, enabling seamless integration of AI-driven workflows with Building Automation (BAS), Industrial Control (ICS) and Smart Home systems, allowing agents to monitor real-time sensor data, actuate devices, and orchestrate complex automation tasks.

Getting Started

Use uv to add and manage the MQTT MCP server as a dependency in your project, or install it directly via uv pip install or pip install. See the Installation section of the documentation for full installation instructions and more details.

uv add mqtt-mcp

The server can be embedded in and run directly from your application. By default, it exposes a Streamable HTTP endpoint at http://127.0.0.1:8000/mcp/.

# app.py
from mqtt_mcp import MQTTMCP

mcp = MQTTMCP()

if __name__ == "__main__":
    mcp.run(transport="http")

It can also be launched from the command line using the provided CLI without modifying the source code.

mqtt-mcp

Or in an ephemeral, isolated environment using uvx. Check out the Using tools guide for more details.

uvx mqtt-mcp

Configuration

For the use cases where most operations target a specific MQTT broker its connection settings (host and port) can be specified at runtime using environment variables so that all prompts that omit explicit connection parameters will be routed to this broker.

export MQTT_MCP_MQTT__HOST=10.0.0.1
export MQTT_MCP_MQTT__PORT=1883

These settings can also be specified in a .env file in the working directory.

# .env
mqtt_mcp_mqtt__host=10.0.0.1
mqtt_mcp_mqtt__port=1883

MCP Inspector

To confirm the server is up and running and explore available resources and tools, run the MCP Inspector and connect it to the MQTT MCP server at http://127.0.0.1:8000/mcp/. Make sure to set the transport to Streamable HTTP.

npx @modelcontextprotocol/inspector

Core Concepts

The MQTT MCP server leverages FastMCP 2.0's core building blocks - resource templates, tools, and prompts - to streamline MQTT receive and publish operations with minimal boilerplate and a clean, Pythonic interface.

Receive Message

Each topic on a device is mapped to a resource (and exposed as a tool) and resource templates are used to specify connection details (host, port) and receive parameters (topic, timeout).

@mcp.resource("mqtt://{host}:{port}/{topic*}")
@mcp.tool(
    annotations={
        "title": "Receive Message",
        "readOnlyHint": True,
        "openWorldHint": True,
    }
)
async def receive_message(
    topic: str,
    host: str = settings.mqtt.host,
    port: int = settings.mqtt.port,
    timeout: int = 60,
) -> str:
    """Receives a message published to the specified topic, if any."""
    ...

Publish Message

Publish operations are exposed as a tool, accepting the same connection details (host, port) and allowing to publish a message to a specific topic in a single, atomic call.

@mcp.tool(
    annotations={
        "title": "Publish Message",
        "readOnlyHint": False,
        "openWorldHint": True,
    }
)
async def publish_message(
    topic: str,
    message: str,
    host: str = settings.mqtt.host,
    port: int = settings.mqtt.port,
) -> str:
    """Publishes a message to the specified topic."""
    ...

Authentication

To enable authentication using the built-in AuthKit provider for the Streamable HTTP transport, provide the AuthKit domain and redirect URL in the .env file. Check out the AuthKit Provider section for more details.

Interactive Prompts

Structured response messages are implemented using prompts that help guide the interaction, clarify missing parameters, and handle errors gracefully.

@mcp.prompt(name="mqtt_help", tags={"mqtt", "help"})
def mqtt_help() -> list[Message]:
    """Provides examples of how to use the MQTT MCP server."""
    ...

Here are some example text inputs that can be used to interact with the server.

Publish {"foo":"bar"} to topic "devices/foo" on 127.0.0.1:1883.
Receive a message from topic "devices/bar", waiting up to 30 seconds.

Examples

The examples folder contains sample projects showing how to integrate with the MQTT MCP server using various client APIs to provide tools and context to LLMs.

• openai-agents - shows how to connect to the MQTT MCP server using the OpenAI Agents SDK.
• openai - a minimal app leveraging remote MCP server support in the OpenAI Python library.
• pydantic-ai - shows how to connect to the MQTT MCP server using the PydanticAI Agent Framework.

Docker

The MQTT MCP server can be deployed as a Docker container as follows:

docker run -dit \
  --name mqtt-mcp \
  --restart=always \
  -p 8080:8000 \
  --env-file .env \
  ghcr.io/ezhuk/mqtt-mcp:latest

This maps port 8080 on the host to the MCP server's port 8000 inside the container and loads settings from the .env file, if present.

License

The server is licensed under the MIT License.