EMQX MCP服务器

Name: EMQX MCP服务器
Author: Benniu

作者：Benniu21 星标更新：2025-03-13

安装使用来源：spider==github.com

项目介绍

EMQX MCP Server

这是一个实现了 Model Context Protocol (MCP) 的服务器，提供与 EMQX MQTT 中间件交互的功能。使 MCP 客户端能够与部署在 EMQX Cloud 或自托管集群上的 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 (布尔值，可选)：按干净启动标志过滤
- 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 Cloud 还是自托管部署）发布 MQTT 消息
输入参数：
- topic (字符串，必需)：要发布的 MQTT 主题
- payload (字符串，必需)：要发布的消息内容
- qos (数字，可选)：服务质量级别（0、1 或 2）（默认值：0）
- retain (布尔值，可选)：是否保留消息（默认值：false）

设置 EMQX 集群

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

EMQX Cloud 无服务器部署：

最简单的开始方式。
从 EMQX Cloud 获取免费的无服务器部署
在 EMQX Cloud 无服务器注册

EMQX Cloud 专用部署：

提供专用于生产工作负载的资源
提供增强的性能、可靠性和定制选项
支持多种云提供商（AWS、GCP、Azure）
包括专业服务等级协议和支持
在 EMQX Cloud 专用创建部署

自托管 EMQX 平台：

下载并本地部署 EMQX 平台
跟随 EMQX 平台的安装说明

在 Claude Desktop 应用程序上本地运行

方案 1：通过 Smithery 安装

要通过 Smithery 自动安装 emqx-mcp-server：

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

方案 2：Docker

如果尚未安装，请安装 Claude Desktop 应用程序。
拉取镜像：
```
docker pull benniuji/emqx-mcp-server
```

将以下内容添加到您的 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

打开或重新启动 Claude Desktop 应用程序
尝试让 Claude 对 MQTT 中间件执行某些操作（例如，请求它向某个主题发布 MQTT 消息）。

方案 3：手动安装

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

如果尚未安装，请安装 Claude Desktop 应用程序。
克隆此仓库。

将以下内容添加到您的 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 实例。

打开或重新启动 Claude Desktop 应用程序
尝试让 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'。让我为您完成这件事。
...
我已经成功地将这首诗以 QoS 1 发布到了主题 '/poem'。消息已通过 ID 00062F55A1EFB1156ABC481240B30000 发送。

我发送的诗如下：

- 信号在太空中，
- 不可见的线相连，
- 设备在低语，
- 跨越数字鸿沟。
- 消息如落叶，
- 从云端落到地面，
- 连接却未束缚，
- 在寂静中无声。
- 现代时代的经纪人，
- 从这里到那里路由梦想，
- 在这张连接网中，
- 我们发现自己无处不在。
- 如星座中的星星，
- 每一点光都有价值，
- 机器的语言，
- 重新定义我们的地球。

您是否希望对您的 MQTT 中间件执行其他操作？

用户：

请踢出客户端 mqttx_2232bdb1

LLM：

我将为您断开该客户端与 MQTT 中间件的连接。
...
客户端已成功断开。系统返回：
> 客户端 mqttx_2232bdb1 已被断开
ID 为 "mqttx_2232bdb1" 的 MQTT 客户端现已从您的中间件断开。您是否希望对您的 MQTT 中间件执行其他操作？

许可证

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