EMQX MCP Server

EMQX MCP Server

一个 Model Context Protocol (MCP) 服务实现，提供与 EMQX MQTT broker 的交互。 使 MCP 客户端能够与 EMQX Cloud 上的 MQTT 集群或自托管集群进行交互

功能

MQTT 客户端管理

• 客户端列表：查看所有已连接的 MQTT 客户端，支持灵活的筛选选项
• 客户端信息：获取特定客户端的详细信息
• 连接控制：从 broker 断开有问题或已失效的客户端
• 灵活筛选：按节点、用户名、客户端 ID、连接状态等筛选客户端

MQTT 消息发布

• 基于主题发布：向任意 MQTT 主题发送消息
• QoS 控制：选择服务质量等级（0、1 或 2）以实现可靠投递
• 消息保留：可选择为新订阅者持久保留消息
• 自定义负载：支持任意消息内容格式

MQTT 主题订阅（SSE）

• 实时订阅：通过 Server-Sent Events（SSE）订阅 MQTT 主题
• 时长控制：配置监听消息的时长（1-300 秒）
• 消息数量限制：设置每次订阅收集的最大消息数量
• 自动解析：消息会自动从 SSE 事件流中解析

工具

list_mqtt_clients

• 列出已连接到你的 EMQX 集群的 MQTT 客户端
• 输入：
  • page (number, 可选)：页码（默认：1）
  • limit (number, 可选)：每页结果数（默认：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 broker 断开某个客户端
• 输入：
  • clientid (string, 必填)：要断开的客户端的唯一标识符

publish_mqtt_message

• 向你在 EMQX Cloud 或自管理部署上的 EMQX 集群发布 MQTT 消息
• 输入：
  • topic (string, 必填)：要发布到的 MQTT 主题
  • payload (string, 必填)：要发布的消息内容
  • qos (number, 可选)：服务质量等级（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 工具之前，你需要设置一个 EMQX 集群，并正确配置 API Key 和客户端认证。有以下几种选择：

1. EMQX Cloud Serverless 部署：

• 最简便的上手方式。
• 从 EMQX Cloud 获取免费的 serverless 部署
• 在 EMQX Cloud Serverless 注册

2. EMQX Cloud Dedicated 部署：

• 为生产工作负载提供专用资源
• 提供更强的性能、可靠性和自定义选项
• 支持多种云服务商（AWS、GCP、Azure）
• 包含专业的 SLA 和支持
• 在 EMQX Cloud Dedicated 创建部署

3. 可自托管的 EMQX Platform：

• 在本地下载并部署 EMQX Platform
• 按照 EMQX Platform 上的安装说明操作

注意： 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 broker 执行一些操作（例如让它向某个主题发布一条 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 broker 执行一些操作（例如让它向某个主题发布一条 MQTT 消息）。

示例提示词

用户：

Please list the clients connected to the MQTT broker.

大模型：

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?

用户：

Yes, please provide the detail info of this client. 

大模型：

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?

用户：

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

大模型：

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?

用户：

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

大模型：

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?

用户：

Please kick out the client mqttx_2232bdb1

大模型

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 文件。