MCP HubMCP Hub
Benniu

emqx-mcp-server

by: Benniu

A Model Context Protocol (MCP) server implementation that provides EMQX MQTT broker interaction.

12created 28/02/2025
Visit
MQTT
EMQX

📌Overview

Purpose: To facilitate interaction between MCP clients and EMQX MQTT broker through a Model Context Protocol (MCP) server implementation.

Overview: The EMQX MCP Server is designed to manage MQTT client connections and message publishing for both EMQX Cloud and self-hosted clusters, offering an efficient way to control and monitor MQTT operations seamlessly.

Key Features:

  • MQTT Client Management: Enables viewing, filtering, and controlling connected MQTT clients, allowing users to manage connections effectively, including disconnecting problematic clients.

  • MQTT Message Publishing: Supports sending asynchronous messages to MQTT topics with control over Quality of Service (QoS) levels, message retention options, and customization of message payloads.

EMQX MCP Server

A Model Context Protocol (MCP) server implementation that provides EMQX MQTT broker interaction.
Enables MCP clients to interact with MQTT clusters on EMQX Cloud or self-hosted clusters.

Features

MQTT Client Management

  • Client Listing: View all connected MQTT clients with flexible filtering options
  • Client Information: Retrieve detailed information about specific clients
  • Connection Control: Disconnect problematic or stale clients from the broker
  • Flexible Filtering: Filter clients by node, username, client ID, connection state, and more

MQTT Message Publishing

  • Topic-based Publishing: Send messages to any MQTT topics
  • QoS Control: Select Quality of Service level (0, 1, or 2) for reliable delivery
  • Message Retention: Option to persist messages for new subscribers
  • Custom Payloads: Support for any message content format

Tools

list_mqtt_clients

List MQTT clients connected to your EMQX Cluster
Inputs:

  • page (number, optional): Page number (default: 1)
  • limit (number, optional): Results per page (default: 100, max 10000)
  • node (string, optional): Filter by specific node name
  • clientid (string, optional): Filter by specific client ID
  • username (string, optional): Filter by specific username
  • ip_address (string, optional): Filter by client IP address
  • conn_state (string, optional): Filter by connection state
  • clean_start (boolean, optional): Filter by clean start flag
  • proto_ver (string, optional): Filter by protocol version
  • like_clientid (string, optional): Fuzzy search by client ID pattern
  • like_username (string, optional): Fuzzy search by username pattern
  • like_ip_address (string, optional): Fuzzy search by IP address pattern

get_mqtt_client

Get detailed information about a specific MQTT client by client ID
Inputs:

  • clientid (string, required): The unique identifier of the client to retrieve

kick_mqtt_client

Disconnect a client from the MQTT broker by client ID
Inputs:

  • clientid (string, required): The unique identifier of the client to disconnect

publish_mqtt_message

Publish an MQTT Message to Your EMQX Cluster on EMQX Cloud or Self-Managed Deployment
Inputs:

  • topic (string, required): MQTT topic to publish to
  • payload (string, required): Message content to publish
  • qos (number, optional): Quality of Service level (0, 1, or 2) (default: 0)
  • retain (boolean, optional): Whether to retain the message (default: false)

Setup EMQX Cluster

Before using the EMQX MCP Server tools, set up an EMQX cluster with properly configured API Key and client authentication. Options include:

  1. EMQX Cloud Serverless Deployment

  2. EMQX Cloud Dedicated Deployment

    • Provides dedicated resources for production workloads
    • Offers enhanced performance, reliability, and customization
    • Supports AWS, GCP, Azure
    • Includes professional SLA and support
    • Create a deployment at https://www.emqx.com/en/cloud/dedicated

  3. Self-hosted EMQX Platform

Running Locally with the Claude Desktop App

Option 1: Installing via Smithery

To install emqx-mcp-server for Claude Desktop automatically, run:

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

Option 2: Docker

  1. Install Claude Desktop App if you haven't yet.

  2. Pull the image:

    docker pull benniuji/emqx-mcp-server

  3. Add the following to your claude_desktop_config.json file:

    • On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • On 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"
      ]
    }
  }
}
  1. Update the environment variables EMQX_API_URL, EMQX_API_KEY, and EMQX_API_SECRET.
  2. Open or restart Claude Desktop App.
  3. Interact with MQTT broker via Claude (e.g., publish a message).

Option 3: Manual Installation

  1. Ensure you have the uv executable installed. Instructions: https://docs.astral.sh/uv/
  2. Install Claude Desktop App if you haven't yet.
  3. Clone this repository.
  4. Add the following to your claude_desktop_config.json file:
  • On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • On 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>"
      }
    }
  }
}
  1. Update the directory path and environment variables accordingly.
  2. Open or restart Claude Desktop App.
  3. Interact with MQTT broker via Claude.

Example Prompts

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 perform another action?

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.

I've successfully published the poem to '/poem' with QoS 1. Message ID: 00062F55A1EFB1156ABC481240B30000.

The poem:

- 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 kick out the client mqttx_2232bdb1

LLM:

I'll disconnect the client from the MQTT broker for you.

The client has been successfully disconnected:
> Client mqttx_2232bdb1 has been disconnected

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

License

This project is licensed under the Apache License Version 2.0. See the LICENSE file for details.