OMNI-MQTT-MCP

OMNI-MQTT-MCP

MQTT MCP 服务，可通过 CLI 配置传输选项：STDIO（默认）、Streamable HTTP（推荐用于 Web）和 SSE（已弃用）。

🚀 快速开始

# 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 CLI 参数选择传输方式：

1. STDIO 传输（默认）✅

python mqtt_mcp_server.py --transport stdio
# or simply:
python mqtt_mcp_server.py

• 最适合：本地开发、集成 Claude Desktop
• 优点：简单、安全，适用于 Claude Desktop 等 MCP 客户端
• 缺点：仅限本地，无法远程访问

2. Streamable HTTP（推荐用于 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

• 最适合：Web 部署、远程访问、微服务
• 默认 URL：http://127.0.0.1:8000/mcp
• 优点：现代、高效、支持多个客户端、易于部署
• 缺点：需要进行网络设置，并考虑安全问题

3. SSE（服务器发送事件）⚠️ 已弃用

python mqtt_mcp_server.py --transport sse

• 最适合：旧版部署（不建议用于新项目）
• 默认 URL：http://127.0.0.1:8000/sse
• 状态：正逐步淘汰，改用 Streamable HTTP

🛠 可用工具

• mqtt_publish：向 MQTT 主题发布消息
• mqtt_subscribe：订阅 MQTT 主题并接收消息

⚙️ 配置选项

MQTT 配置

python mqtt_mcp_server.py \
  --broker localhost \
  --port 1883 \
  --client-id mcp-mqtt-client \
  --username your_username \
  --password your_password

传输配置

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

所有选项

python mqtt_mcp_server.py --help

环境变量

你也可以使用环境变量配置 MQTT 设置：

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

🧪 测试

测试 HTTP 服务

# Terminal 1: Start server
python mqtt_mcp_server.py --transport streamable-http

# Terminal 2: Test it
python test_http_client.py

使用 Claude Desktop 测试

将以下内容添加到 Claude Desktop MCP 配置中：

{
  "mcpServers": {
    "mqtt": {
      "command": "python",
      "args": ["/path/to/mqtt_mcp_server.py"],
      "env": {
        "MQTT_BROKER_ADDRESS": "localhost",
        "MQTT_PORT": "1883"
      }
    }
  }
}

🔧 开发

使用 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

📚 示例

本地开发

# Default STDIO for Claude Desktop
python mqtt_mcp_server.py

Web 部署

# 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

使用自定义 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

🤔 应该选择哪种传输方式？

使用场景	命令	原因？
本地开发	python mqtt_mcp_server.py	简单、安全，适用于 Claude Desktop
Web 部署	python mqtt_mcp_server.py --transport streamable-http	现代、高效、易于部署
远程 AI Agent	python mqtt_mcp_server.py --transport streamable-http --host 0.0.0.0	支持身份验证，可扩展
旧版系统	python mqtt_mcp_server.py --transport sse	仅适用于已在使用 SSE 的情况

🐳 使用 Ngrok 的 Docker

在 Docker 中运行服务，并通过 ngrok 隧道自动将其公开。

构建

docker build -t mqtt-mcp-ngrok .

运行

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

容器通过 ngrok 暴露 MCP 服务。传入环境变量以配置 MQTT broker 和服务传输方式。查看容器日志以获取公开 URL。

📚 了解更多

• Model Context Protocol 规范
• MCP Python SDK
• FastMCP 文档

🔒 安全说明

• STDIO：在本地运行，本身安全
• HTTP/SSE：生产部署时请考虑添加身份验证
• MQTT：配置 MQTT broker 安全性（TLS、身份验证）