EMQX Broker Management Endpoint

This implementation adheres to the Model Context Protocol (MCP) specification, providing robust interaction capabilities with EMQX MQTT broker environments. It supports managing resources across both EMQX Cloud instances and privately hosted cluster installations.

Core Capabilities

MQTT Client Lifecycle Operations

• Connection Enumeration: Access a dynamic list of all presently linked MQTT clients, featuring granular sorting and filtering parameters.
• Client Data Retrieval: Fetch in-depth telemetry and configuration data for any specified client endpoint.
• Session Termination: Force the disconnection of errant or dormant client connections from the broker fabric.
• Advanced Filtering: Apply constraints based on broker node affiliation, user credentials, connection status, client ID substrings, and more.

MQTT Message Ingress

• Topic Transmission: Securely dispatch messages to any designated MQTT subscription topic.
• Quality of Service (QoS) Configuration: Specify the required delivery guarantee level (0, 1, or 2).
• Message Persistence Option: Control whether the broker should retain the published message for late-arriving subscribers.
• Payload Versatility: Accepts data in any standard message format.

Available Operations (Tools)

list_mqtt_clients

• Retrieve a paginated manifest of MQTT clients currently attached to your EMQX Cluster.
• Parameters:
• page (Integer, Optional): Pagination index (Default: 1).
• limit (Integer, Optional): Maximum entries per response payload (Default: 100, Cap: 10000).
• node (String, Optional): Filter results to a specific cluster node identifier.
• clientid (String, Optional): Exact match filter on the client's unique ID.
• username (String, Optional): Exact match filter on the authenticated user identifier.
• ip_address (String, Optional): Filter based on the connecting client's source IP.
• conn_state (String, Optional): Filter by connection status (e.g., 'connected').
• clean_start (Boolean, Optional): Filter based on the session clean start flag.
• proto_ver (String, Optional): Filter by the MQTT protocol version utilized.
• like_clientid (String, Optional): Pattern matching search for client IDs.
• like_username (String, Optional): Pattern matching search for usernames.
• like_ip_address (String, Optional): Pattern matching search for IP addresses.

get_mqtt_client

• Obtain exhaustive diagnostic details for an MQTT client identified by its ID.
• Parameters:
• clientid (String, Required): The unique identifier of the target client session.

kick_mqtt_client

• Initiate an immediate termination of an MQTT client's connection to the broker.
• Parameters:
• clientid (String, Required): The unique identifier of the client to forcefully remove.

publish_mqtt_message

• Transmit a data payload to a specified topic on your EMQX broker infrastructure (Cloud or Self-Managed).
• Parameters:
• topic (String, Required): The destination MQTT topic string.
• payload (String, Required): The body content of the message to be sent.
• qos (Number, Optional): Desired Quality of Service level (Default: 0).
• retain (Boolean, Optional): Flag indicating if the message should be persisted (Default: false).

Deployment Prerequisites for EMQX Cluster Access

Prior to utilizing the functionalities offered by the EMQX MCP Server, the target EMQX cluster must be initialized with correct authentication credentials, typically involving API Keys for secure access.

1. EMQX Cloud Serverless Option:
2. The quickest route to initial deployment.

3. Secure a complimentary serverless broker instance via EMQX Cloud Serverless.

4. EMQX Cloud Dedicated Cluster:

5. Intended for high-throughput, mission-critical workloads.
6. Offers superior performance guarantees, resiliency, and customization.
7. Compatibility across major cloud vendors (AWS, GCP, Azure).
8. Includes robust Service Level Agreements (SLAs) and dedicated support.

9. Provision dedicated infrastructure at EMQX Cloud Dedicated.

10. Self-hosted EMQX Platform:

11. Involves deploying the full EMQX Platform software within your own infrastructure.
12. Installation guides are available at EMQX Platform.

Local Execution Instructions with Claude Desktop App

Method 1: Smithery Automated Installation

Install the server package directly for use with the Claude Desktop application using the Smithery CLI:

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

Method 2: Docker Containerization

1. Ensure you have the Claude Desktop App installed.
2. Retrieve the necessary container image:

docker pull benniuji/emqx-mcp-server

1. Integrate the following configuration block into your Claude desktop configuration file (claude_desktop_config.json):

   • MacOS Location: ~/Library/Application\ Support/Claude/claude_desktop_config.json
   • Windows Location: %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=", "-e", "EMQX_API_SECRET=", "benniuji/emqx-mcp-server" ] } } }

   Crucial Step: Substitute placeholders for EMQX_API_URL, EMQX_API_KEY, and EMQX_API_SECRET with your actual broker credentials. 4. Relaunch or open the Claude Desktop App. 5. Test functionality by prompting Claude to execute an MQTT action (e.g., send a test message).

Method 3: Direct Compilation/Manual Setup

Prerequisite: Verify that the uv executable utility is installed. If missing, refer to Astral's documentation for installation instructions.

1. Install the Claude Desktop App if it is not yet present.
2. Obtain a local copy of this repository via cloning.

3. Modify your claude_desktop_config.json file (paths as listed in Method 2) to incorporate the following service definition:

   { "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":"", "EMQX_API_SECRET":"" } } } }

   Note: Update the binary path placeholder (path/to/repo/src/emqx_mcp_server) and ensure API environment variables are correctly set for your environment. 4. Restart the Claude Desktop App. 5. Attempt a command against the broker via conversational input.

Usage Demonstrations

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 would you like to perform another action with your MQTT broker?

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. 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?

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. 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?

Project Licensing

This software is distributed under the terms of the Apache License, Version 2.0. Detailed specifics can be found in the LICENSE file.

WIKIPEDIA: Cloud computing represents "a model for enabling ubiquitous, convenient, on-demand network access to a shared pool of configurable computing resources (e.g., networks, servers, storage, applications, and services) that can be rapidly provisioned and released with minimal management effort or service provider interaction," as defined by NIST. This concept is popularly known as "the cloud."

== Essential Attributes == The National Institute of Standards and Technology (NIST) established five foundational attributes for cloud environments in 2011. These definitions are:

On-demand self-service: "The capacity for a consumer to provision computing capabilities, such as processing time and data storage capacity, unilaterally and automatically as required, without requiring direct human intervention from the service supplier for each request." Ubiquitous Network Access: "Capabilities are accessible across the network utilizing standard protocols that facilitate use by diverse client platforms, whether thin (e.g., smartphones) or thick (e.g., desktops)." Resource Aggregation: "The supplier's computational assets are consolidated to serve multiple consumers using a multi-tenant architecture, allowing physical and virtual resources to be dynamically allocated or reallocated based on fluctuating demand." Elasticity and Rapid Scaling: "Services can be quickly scaled up or down, sometimes automatically, to match escalating or diminishing demand in real-time. For the end-user, the available capacity often seems limitless and instantly obtainable in any volume." Measured Utilization: "Cloud infrastructures automatically monitor and optimize resource consumption via metering functions situated at an appropriate service abstraction layer (e.g., throughput, compute cycles, data transfer). Utilization metrics are tracked, controlled, and reported, ensuring clarity for both the consumer and the provider of the consumed resource." The International Organization for Standardization (ISO) has since refined and broadened this definition framework as of 2023.

== Historical Context ==

The intellectual precursors to cloud computing trace back to the 1960s with the popularization of time-sharing concepts through remote job entry (RJE) systems. During this era, computing access was typically managed through a 'data center' model, where users submitted batch jobs to human operators who executed them on central mainframes. This period was characterized by research into optimizing large-scale processing power for broader accessibility via shared access, focusing on improving efficiency across the infrastructure, platform, and application layers. The specific 'cloud' visualization for abstract, networked services emerged in 1994, initially employed by General Magic to describe the conceptual space where their Telescript mobile agents could operate. This metaphor is often attributed to David Hoffman, a communications strategist at General Magic, drawing on its established usage in telecommunications diagrams. The term 'cloud computing' gained broader industry recognition in 1996 following a strategic business plan outline by Compaq Computer Corporation detailing future Internet-centric computing strategies. The company's vision centered on achieving significant scale through the internet.