OMNI-MQTT-MCP

OMNI-MQTT-MCP

CLI からトランスポートオプションを設定できる MQTT MCP サーバー：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（Server-Sent Events） ⚠️ 非推奨

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 エージェント	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 ブローカーとサーバーのトランスポートを設定してください。コンテナのログを確認し、 公開 URL を確認します。

📚 詳細情報

• Model Context Protocol の仕様
• MCP Python SDK
• FastMCP ドキュメント

🔒 セキュリティに関する注意事項

• STDIO：ローカルで実行されるため、本質的に安全です
• HTTP/SSE：本番環境へのデプロイでは、認証の追加を検討してください
• MQTT：MQTT ブローカーのセキュリティ（TLS、認証）を設定してください