EMQX MCP 服务器

一个实现了模型上下文协议（MCP）的服务器，提供与EMQX MQTT代理的交互能力。
支持MCP客户端与EMQX云或自托管集群中的MQTT集群进行交互。

功能特性

MQTT 客户端管理

• 客户端列表：使用灵活的过滤选项查看所有连接的MQTT客户端
• 客户端信息：获取特定客户端的详细信息
• 连接控制：从代理断开问题或闲置的客户端
• 灵活过滤：按节点、用户名、客户端ID、连接状态等过滤客户端

MQTT 消息发布

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

工具

list_mqtt_clients

• 列出连接到您的EMQX集群的MQTT客户端
• 输入参数：
  • page（数字，可选）：页码（默认：1）
  • limit（数字，可选）：每页结果数（默认：100，最大10000）
  • node（字符串，可选）：按特定节点名称过滤
  • clientid（字符串，可选）：按特定客户端ID过滤
  • username（字符串，可选）：按特定用户名过滤
  • ip_address（字符串，可选）：按客户端IP地址过滤
  • conn_state（字符串，可选）：按连接状态过滤
  • clean_start（布尔值，可选）：按clean start标志过滤
  • proto_ver（字符串，可选）：按协议版本过滤
  • like_clientid（字符串，可选）：按客户端ID模式模糊搜索
  • like_username（字符串，可选）：按用户名模式模糊搜索
  • like_ip_address（字符串，可选）：按IP地址模式模糊搜索

get_mqtt_client

• 通过客户端ID获取特定MQTT客户端的详细信息
• 输入参数：
  • clientid（字符串，必填）：要检索的客户的唯一标识符

kick_mqtt_client

• 通过客户端ID从MQTT代理断开客户端
• 输入参数：
  • clientid（字符串，必填）：要断开的客户的唯一标识符

publish_mqtt_message

• 在EMQX云或自托管部署上向您的EMQX集群发布MQTT消息
• 输入参数：
  • topic（字符串，必填）：要发布的MQTT主题
  • payload（字符串，必填）：要发布的消息内容
  • qos（数字，可选）：服务质量等级（0、1或2）（默认：0）
  • retain（布尔值，可选）：是否保留消息（默认：false）

设置EMQX集群

在使用EMQX MCP服务器工具之前，您需要设置一个配置了正确API密钥和客户端认证的EMQX集群。有几种选择：

1. EMQX云无服务器部署：

   • 最简单的入门方式。
   • 从EMQX云获取免费的无服务器部署
   • 在EMQX云无服务器注册

2. EMQX云专用部署：

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

3. 自托管EMQX平台：

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

使用Claude桌面应用程序本地运行

选项1：通过Smithery安装

要通过Smithery自动为Claude桌面安装emqx-mcp-server：

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

选项2：Docker

1. 如果尚未安装，请安装Claude桌面应用程序。

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桌面应用程序

5. 尝试让Claude使用MQTT代理执行某些操作（例如，让它向主题发布MQTT消息）。

选项3：手动安装

首先，确保您已安装uv可执行文件。如果没有，可以按照这里的说明进行安装。

1. 如果尚未安装，请安装Claude桌面应用程序。
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桌面应用程序
5. 尝试让Claude使用MQTT代理执行某些操作（例如，让它向主题发布MQTT消息）。

示例提示

用户：

请列出连接到MQTT代理的客户端。

LLM：

以下是当前连接到您的MQTT代理的客户端：
连接的客户端：
  - 客户端ID：mqttx_2232bdb1
  - 用户名：test
  - 协议：MQTT v5
  ...
当前有1个客户端连接到您的MQTT代理。您是否需要关于此特定客户端的更详细信息，或者您想对MQTT代理执行其他操作？

用户：

是的，请提供此客户端的详细信息。

LLM：

我将为您检索此客户端的详细信息。
...
这是客户端"mqttx_2232bdb1"的详细信息：

**基本信息：**
-   **客户端ID：** mqttx_2232bdb1
-   **用户名：** test
...
**连接详情：**
-   **已连接：** 是
-   **创建时间：** 2025-03-02T05:29:51.103+00:00
...
您是否想对此客户端执行任何操作，例如向主题发布消息或断开客户端连接？

用户：

请写一首诗并发送到主题'/poem'，QoS为1。

LLM：

我将创建一首诗并以QoS 1发布到主题'/poem'。让我为您完成。
...
我已成功将诗歌发布到主题'/poem'，QoS为1。消息已交付，ID为：00062F55A1EFB1156ABC481240B30000。

我发送的诗是：

- 以太中的信号，
- 无形之线相连，
- 设备低语交流，
- 跨越数字鸿沟。
- 如叶落般的信息，
- 从云端飘向地面，
- 相连却无束缚，
- 寂静无声之处。
- 现代时代的代理，
- 在此间路由梦想，
- 在这连接之网，
- 我们无处不在。
- 如星座中的星辰，
- 每一点光都有价值，
- 机器的语言，
- 重新定义我们的地球。

您还想对MQTT代理执行其他操作吗？

用户：

请踢出客户端mqttx_2232bdb1

LLM

我将为您断开该客户端与MQTT代理的连接。
...
客户端已成功断开连接。系统返回：
> 客户端mqttx_2232bdb1已被断开连接
客户端ID为"mqttx_2232bdb1"的MQTT客户端现已从您的代理断开连接。您还想对MQTT代理执行其他操作吗？

许可证

本项目根据Apache许可证2.0版授权 - 详情请参阅LICENSE文件。