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.py

Best 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 9000

Best for: Web deployments, remote access, microservices
Default URL: http://127.0.0.1:8000/mcp
Pros: 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 sse

Best for: Legacy deployments (not recommended for new projects)
Default URL: http://127.0.0.1:8000/sse
Status: Being phased out in favor of Streamable HTTP

🛠 Available Tools

mqtt_publish: Publish messages to MQTT topics
mqtt_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_password

Transport Configuration

python mqtt_mcp_server.py \
  --transport streamable-http \
  --host 127.0.0.1 \
  --http-port 8000 \
  --path /mcp

All Options

python mqtt_mcp_server.py --help

Environment 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.py

Test 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.py

Web 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/mcp

Production 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	`python mqtt_mcp_server.py`	Simple, secure, works with Claude Desktop
Web deployment	`python mqtt_mcp_server.py --transport streamable-http`	Modern, efficient, easy to deploy
Remote AI agents	`python mqtt_mcp_server.py --transport streamable-http --host 0.0.0.0`	Supports authentication, scalable
Legacy systems	`python mqtt_mcp_server.py --transport sse`	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-ngrok

The 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)