EMQX MCP Server

EMQX MCP サーバー

EMQX MQTT ブローカーとの連携を提供する Model Context Protocol (MCP) サーバーの実装です。 MCP クライアントが EMQX Cloud またはセルフホスト型クラスター上の MQTT クラスターと連携できるようにします

機能

MQTT クライアント管理

• クライアント一覧: 接続されているすべての MQTT クライアントを柔軟なフィルタリングオプションで表示します
• クライアント情報: 特定のクライアントに関する詳細情報を取得します
• 接続制御: 問題のあるクライアントや古いクライアントをブローカーから切断します
• 柔軟なフィルタリング: ノード、ユーザー名、クライアント ID、接続状態などでクライアントをフィルタリングします

MQTT メッセージのパブリッシュ

• トピックベースのパブリッシュ: 任意の MQTT トピックにメッセージを送信します
• QoS 制御: 信頼性の高い配信のために Quality of Service レベル (0、1、2) を選択します
• メッセージ保持: 新しいサブスクライバー向けにメッセージを保持するオプション
• カスタムペイロード: あらゆるメッセージコンテンツ形式をサポートします

MQTT トピックのサブスクリプション (SSE)

• リアルタイムサブスクリプション: Server-Sent Events (SSE) 経由で MQTT トピックをサブスクライブします
• 期間制御: メッセージをリッスンする時間 (1〜300 秒) を設定します
• メッセージ数制限: サブスクリプションごとに収集するメッセージの最大数を設定します
• 自動パース: メッセージは SSE イベントストリームから自動的にパースされます

ツール

list_mqtt_clients

• EMQX クラスターに接続されている MQTT クライアントを一覧表示します
• 入力:
  • page (number, 任意): ページ番号 (デフォルト: 1)
  • limit (number, 任意): 1 ページあたりの結果数 (デフォルト: 100、最大 10000)
  • node (string, 任意): 特定のノード名でフィルタリングします
  • clientid (string, 任意): 特定のクライアント ID でフィルタリングします
  • username (string, 任意): 特定のユーザー名でフィルタリングします
  • ip_address (string, 任意): クライアントの IP アドレスでフィルタリングします
  • conn_state (string, 任意): 接続状態でフィルタリングします
  • clean_start (boolean, 任意): clean start フラグでフィルタリングします
  • proto_ver (string, 任意): プロトコルバージョンでフィルタリングします
  • like_clientid (string, 任意): クライアント ID パターンによる曖昧検索
  • like_username (string, 任意): ユーザー名パターンによる曖昧検索
  • like_ip_address (string, 任意): IP アドレスパターンによる曖昧検索

get_mqtt_client

• クライアント ID を指定して特定の MQTT クライアントの詳細情報を取得します
• 入力:
  • clientid (string, 必須): 取得するクライアントの一意の識別子

kick_mqtt_client

• クライアント ID を指定してクライアントを MQTT ブローカーから切断します
• 入力:
  • clientid (string, 必須): 切断するクライアントの一意の識別子

publish_mqtt_message

• EMQX Cloud またはセルフマネージドデプロイメント上の EMQX クラスターに MQTT メッセージをパブリッシュします
• 入力:
  • topic (string, 必須): パブリッシュ先の MQTT トピック
  • payload (string, 必須): パブリッシュするメッセージコンテンツ
  • qos (number, 任意): Quality of Service レベル (0、1、2) (デフォルト: 0)
  • retain (boolean, 任意): メッセージを保持するかどうか (デフォルト: false)

subscribe_mqtt_topic

• EMQX Cloud 上で SSE 経由で MQTT トピックをサブスクライブし、指定した期間メッセージを収集します
• 入力:
  • topic (string, 必須): サブスクライブする MQTT トピック
  • duration (number, 任意): リッスンする時間 (秒) (1〜300、デフォルト: 30)
  • max_messages (number, 任意): 収集するメッセージの最大数 (1〜1000、デフォルト: 100)
• 戻り値: topic、message_count、messages 配列を含むオブジェクト

EMQX クラスターのセットアップ

EMQX MCP Server のツールを使用する前に、API Key とクライアント認証を適切に設定した EMQX クラスターをセットアップする必要があります。いくつかのオプションがあります:

1. EMQX Cloud Serverless デプロイメント:

• もっとも簡単に始められる方法です。
• EMQX Cloud から無料のサーバーレスデプロイメントを取得します
• EMQX Cloud Serverless でサインアップします

2. EMQX Cloud Dedicated デプロイメント:

• 本番ワークロード向けの専用リソースを提供します
• 強化されたパフォーマンス、信頼性、カスタマイズオプションを提供します
• さまざまなクラウドプロバイダー (AWS、GCP、Azure) をサポートします
• プロフェッショナルな SLA とサポートが含まれます
• EMQX Cloud Dedicated でデプロイメントを作成します

3. セルフホスト型 EMQX Platform:

• EMQX Platform をダウンロードしてローカルにデプロイします
• EMQX Platform のインストール手順に従います

Note: subscribe_mqtt_topic ツールは SSE (Server-Sent Events) エンドポイントを使用します。これは EMQX Cloud デプロイメントで利用可能です。すべてのセルフホスト型 EMQX デプロイメントが SSE サブスクライブエンドポイントをサポートしているわけではありません。

Claude Desktop App を使用したローカルでの実行

オプション 1: Smithery 経由でのインストール

Smithery 経由で Claude Desktop 用の emqx-mcp-server を自動的にインストールするには:

npx -y @smithery/cli install @Benniu/emqx-mcp-server --client claude

オプション 2: Docker

1. まだインストールしていない場合は、Claude Desktop App をインストールします。

2. イメージをプルします:

   docker pull benniuji/emqx-mcp-server
   

3. claude_desktop_config.json ファイルに以下を追加します:

   • MacOS の場合: ~/Library/Application\ Support/Claude/claude_desktop_config.json
   • Windows の場合: %APPDATA%/Claude/claude_desktop_config.json

   {
     "mcpServers": {
       "EMQX_MCP_Server": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-e", "EMQX_API_URL=https://your-emqx-cloud-instance.com:8443/api/v5",
           "-e", "EMQX_API_KEY=<YOUR-API-KEY>",
           "-e", "EMQX_API_SECRET=<YOUR-API-SECRET>",
           "benniuji/emqx-mcp-server"
         ]
       }
     }
   }
   

   注意: 環境変数 EMQX_API_URL、EMQX_API_KEY、EMQX_API_SECRET を更新してください。

4. Claude Desktop App を開くか再起動します

5. Claude に MQTT ブローカーで何かを行うように依頼してみてください (例えば、トピックに MQTT メッセージをパブリッシュするように依頼します)。

オプション 3: 手動インストール

まず、uv 実行ファイルがインストールされていることを確認してください。インストールされていない場合は、こちら の手順に従ってインストールできます。

1. まだインストールしていない場合は、Claude Desktop App をインストールします。
2. このリポジトリをクローンします。
3. claude_desktop_config.json ファイルに以下を追加します:
   • MacOS の場合: ~/Library/Application\ Support/Claude/claude_desktop_config.json
   • Windows の場合: %APPDATA%/Claude/claude_desktop_config.json

   {
     "mcpServers": {
       "EMQX_MCP_Server": {
         "command": "uv",
         "args": [
           "--directory",
           "path/to/repo/src/emqx_mcp_server",
           "run",
           "emqx-mcp-server"
         ],
         "env":{
           "EMQX_API_URL":"https://your-emqx-cloud-instance.com:8443/api/v5",
           "EMQX_API_KEY":"<YOUR-API-KEY>",
           "EMQX_API_SECRET":"<YOUR-API-SECRET>"
         }
       }
     }
   }
   

   注意: path/to/repo/src/emqx_mcp_server を実際のパスに更新し、環境変数 EMQX_API_URL、EMQX_API_KEY、EMQX_API_SECRET をあなたの EMQX インスタンスに合わせて変更してください。
4. Claude Desktop App を開くか再起動します
5. Claude に MQTT ブローカーで何かを行うように依頼してみてください (例えば、トピックに MQTT メッセージをパブリッシュするように依頼します)。

プロンプトの例

User:

Please list the clients connected to the MQTT broker.

LLM:

Here are the clients currently connected to your MQTT broker:
Connected Client:
  - Client ID: mqttx_2232bdb1
  - Username: test
  - Protocol: MQTT v5
  ...
There is currently 1 client connected to your MQTT broker. Would you like more detailed information about this specific client or would you like to perform another action with your MQTT broker?

User:

Yes, please provide the detail info of this client. 

LLM:

I'll retrieve the detailed information for this client for you.
...
Here's the detailed information for client "mqttx_2232bdb1":

**Basic Information:**
-   **Client ID:** mqttx_2232bdb1
-   **Username:** test
...
**Connection Details:**
-   **Connected:** Yes
-   **Created At:** 2025-03-02T05:29:51.103+00:00
...
Would you like to perform any actions with this client, such as publishing a message to a topic or disconnecting the client?

User:

Please write a poem and send it to the topic '/poem' with QoS 1.

LLM:

I'll create a poem and publish it to the topic '/poem' with QoS 1. Let me do that for you.
...
I've successfully published the poem to the topic '/poem' with QoS 1. The message has been delivered with ID: 00062F55A1EFB1156ABC481240B30000.

The poem I sent was:

- Signals in the ether,
- Invisible threads that bind,
- Devices speak in whispers,
- Across the digital divide.
- Messages like leaves falling,
- From cloud to waiting ground,
- Connected yet untethered,
- Where silence makes no sound.
- Brokers of the modern age,
- Routing dreams from here to there,
- In this web of connections,
- We find ourselves everywhere.
- Like stars in constellation,
- Each point of light has worth,
- The language of machines,
- Redefining our Earth.

Is there anything else you'd like to do with your MQTT broker?

User:

Please subscribe to the topic 'sensor/temperature' for 10 seconds and show me the messages.

LLM:

I'll subscribe to the topic 'sensor/temperature' for 10 seconds to collect messages.
...
I received 3 messages from topic 'sensor/temperature' during the 10-second subscription:

1. {"temperature": 23.5, "unit": "celsius", "timestamp": "2025-03-02T10:00:01Z"}
2. {"temperature": 23.6, "unit": "celsius", "timestamp": "2025-03-02T10:00:04Z"}
3. {"temperature": 23.4, "unit": "celsius", "timestamp": "2025-03-02T10:00:07Z"}

Would you like to subscribe for a longer duration or take any other action?

User:

Please kick out the client mqttx_2232bdb1

LLM

I'll disconnect the client from the MQTT broker for you.
...
The client has been successfully disconnected. The system returned:
> Client mqttx_2232bdb1 has been disconnected
The MQTT client with ID "mqttx_2232bdb1" is now disconnected from your broker. Is there anything else you would like to do with your MQTT broker?

ライセンス

このプロジェクトは Apache License Version 2.0 の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。