Supports Docker deployment with containerized server configuration for running the MQTT MCP server in Docker environments.
Provides tools for publishing messages to MQTT topics and subscribing to MQTT topics to receive messages, with configurable broker connection settings including authentication and TLS support.
Enables automatic exposure of the MCP server through ngrok tunnels when running in Docker, providing public URL access to locally hosted instances.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@OMNI-MQTT-MCPpublish 'temperature: 72.5F' to sensor/room1"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
OMNI-MQTT-MCP
MQTT MCP Server with configurable transport options via CLI: STDIO (default), Streamable HTTP (recommended for web), and SSE (deprecated).
🚀 Quick Start
# Install dependencies
pip install -r requirements.txt
# Run with STDIO (default - for local development)
python mqtt_mcp_server.py
# Run with Streamable HTTP (recommended for web)
python mqtt_mcp_server.py --transport streamable-http
# Run with SSE (deprecated)
python mqtt_mcp_server.py --transport sse📋 Transport Options
Choose your transport with the --transport CLI argument:
1. STDIO Transport (Default) ✅
python mqtt_mcp_server.py --transport stdio
# or simply:
python mqtt_mcp_server.pyBest for: Local development, Claude Desktop integration
Pros: Simple, secure, works with MCP clients like Claude Desktop
Cons: Local only, no remote access
2. Streamable HTTP (Recommended for Web) 🌐
python mqtt_mcp_server.py --transport streamable-http
python mqtt_mcp_server.py --transport streamable-http --host 0.0.0.0 --http-port 9000Best for: Web deployments, remote access, microservices
Default URL:
http://127.0.0.1:8000/mcpPros: Modern, efficient, supports multiple clients, easy deployment
Cons: Requires network setup, security considerations
3. SSE (Server-Sent Events) ⚠️ Deprecated
python mqtt_mcp_server.py --transport sseBest for: Legacy deployments (not recommended for new projects)
Default URL:
http://127.0.0.1:8000/sseStatus: Being phased out in favor of Streamable HTTP
🛠 Available Tools
mqtt_publish: Publish messages to MQTT topicsmqtt_subscribe: Subscribe to MQTT topics and receive messages
⚙️ Configuration Options
MQTT Configuration
python mqtt_mcp_server.py \
--broker localhost \
--port 1883 \
--client-id mcp-mqtt-client \
--username your_username \
--password your_passwordTransport Configuration
python mqtt_mcp_server.py \
--transport streamable-http \
--host 127.0.0.1 \
--http-port 8000 \
--path /mcpAll Options
python mqtt_mcp_server.py --helpEnvironment Variables
You can also use environment variables for MQTT settings:
export MQTT_BROKER_ADDRESS=localhost
export MQTT_PORT=1883
export MQTT_CLIENT_ID=mcp-mqtt-client
export MQTT_USERNAME=your_username
export MQTT_PASSWORD=your_password
python mqtt_mcp_server.py --transport streamable-http🧪 Testing
Test HTTP Server
# Terminal 1: Start server
python mqtt_mcp_server.py --transport streamable-http
# Terminal 2: Test it
python test_http_client.pyTest with Claude Desktop
Add to your Claude Desktop MCP configuration:
{
"mcpServers": {
"mqtt": {
"command": "python",
"args": ["/path/to/mqtt_mcp_server.py"],
"env": {
"MQTT_BROKER_ADDRESS": "localhost",
"MQTT_PORT": "1883"
}
}
}
}🔧 Development
Using the MCP CLI
# Run in development mode with MCP Inspector
mcp dev mqtt_mcp_server.py
# Run with specific transport via MCP CLI
mcp run mqtt_mcp_server.py -- --transport streamable-http --http-port 9000📚 Examples
Local Development
# Default STDIO for Claude Desktop
python mqtt_mcp_server.pyWeb Deployment
# HTTP server on port 8000
python mqtt_mcp_server.py --transport streamable-http
# HTTP server on custom port and host
python mqtt_mcp_server.py --transport streamable-http --host 0.0.0.0 --http-port 9000
# Custom path
python mqtt_mcp_server.py --transport streamable-http --path /api/mcpProduction with Custom MQTT
python mqtt_mcp_server.py \
--transport streamable-http \
--broker mqtt.example.com \
--port 8883 \
--username prod_user \
--password secret123 \
--host 0.0.0.0 \
--http-port 80🤔 Which Transport Should I Choose?
Use Case | Command | Why? |
Local development |
| Simple, secure, works with Claude Desktop |
Web deployment |
| Modern, efficient, easy to deploy |
Remote AI agents |
| Supports authentication, scalable |
Legacy systems |
| Only if you're already using SSE |
🐳 Docker with Ngrok
Run the server inside Docker and automatically expose it with an ngrok tunnel.
Build
docker build -t mqtt-mcp-ngrok .Run
docker run -d \
-p 8000:8000 \
-e NGROK_AUTHTOKEN=<YOUR_TOKEN> \
-e TRANSPORT=sse \
-e FASTMCP_PORT=8000 \
-e MQTT_BROKER_ADDRESS=mqtt.example.com \
-e MQTT_PORT=8883 \
-e MQTT_CLIENT_ID=my-client \
-e MQTT_USERNAME=prod_user \
-e MQTT_PASSWORD=secret123 \
mqtt-mcp-ngrokThe container exposes the MCP server via ngrok. Pass environment variables to configure the MQTT broker and server transport. Check the container logs to discover the public URL.
📚 Learn More
🔒 Security Notes
STDIO: Runs locally, inherently secure
HTTP/SSE: Consider adding authentication for production deployments
MQTT: Configure MQTT broker security (TLS, authentication)