EMQX MCP 服务器

这是一个 模型上下文协议 (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 Cloud 或自管理部署上向您的 EMQX 集群发布一条 MQTT 消息
• 输入：
  • topic (字符串, 必须): 发布到的 MQTT 主题
  • payload (字符串, 必须): 要发布的消息内容
  • qos (数字, 可选): 服务质量级别 (0, 1 或 2) (默认: 0)
  • retain (布尔值, 可选): 是否保留消息 (默认: false)

设置 EMQX 集群

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

1. EMQX Cloud 无服务器部署：

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

1. EMQX Cloud 专用部署：

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

1. 自托管 EMQX 平台：

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

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

选项 1：通过 Smithery 安装

通过 Smithery 自动安装 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 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 实例修改环境变量 EMQX_API_URL、EMQX_API_KEY 和 EMQX_API_SECRET。
4. 打开或重启 Claude Desktop App
5. 试着让 Claude 对 MQTT 代理执行某些操作（例如，请求它向某个主题发布一条 MQTT 消息）。

示例提示

用户:

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?

用户:

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?

用户:

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?

用户:

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