mqtt

This MQTT MCP server exposes a Streamable HTTP API that allows LLM agents to interact with MQTT brokers using a standardized Model Context Protocol interface. It maps each MQTT topic to a resource/tool pair, enabling operations such as receiving messages from topics and publishing messages to topics. The server can be embedded directly in your Python application or run via the provided CLI, and can also be deployed in ephemeral environments using uvx. To interact with the server, you can use the MCP Inspector to explore available resources and test tools against the server endpoint at http://127.0.0.1:8000/mcp/. The server supports receive and publish operations as tools, along with prompts to guide interactions and error handling. Authentication via AuthKit can be enabled for the Streamable HTTP transport by configuring domain and redirect URL in the environment or a .env file.

Prerequisites:

• Python 3.8+ installed
• pip or uv (for dependency management)
• Optional: Docker if you prefer containerized deployment

Install via uv (recommended for Python MCP servers):

uv add mqtt-mcp

Or install as a Python package and run the CLI or import the library in your application:

pip install mqtt-mcp

Run the server from your project (embedded in code):

from mqtt_mcp import MQTTMCP

mcp = MQTTMCP()

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

Run the CLI directly (requires the package to be installed):

mqtt-mcp

For ephemeral environments, you can use uvx to run the MCP server:

uvx mqtt-mcp

Docker deployment example is provided in the README under Docker.

Environment variables influence broker connection and authentication behavior. Use a .env file or export variables in your shell:

• MQTT_MCP_MQTT__HOST: MQTT broker hostname
• MQTT_MCP_MQTT__PORT: MQTT broker port (default 1883)
• AUTHKIT_DOMAIN and AUTHKIT_REDIRECT_URL: configure AuthKit-based authentication for Streamable HTTP if you enable it Common issues include:
• MQTT broker unreachable: verify host/port and network access
• Port conflicts: ensure host port 8000 (HTTP API) or container port mappings do not conflict with other services
• Missing .env: ensure environment variables or .env file are present when starting via Docker or uvx
• Inspector connection: set transport to Streamable HTTP and point to http://127.0.0.1:8000/mcp/