Emqx Mcp Server

Emqx Mcp Server

What is Emqx Mcp Server about? Enables MCP clients to manage and communicate with EMQX MQTT clusters, whether hosted on EMQX Cloud (serverless or dedicated) or self‑hosted deployments. It offers HTTP‑based tools that can be invoked by LLMs to perform common broker operations.

How to use Emqx Mcp Server?

1. Deploy the server (Docker, Smithery, or manual uv installation).
2. Set the required environment variables: EMQX_API_URL, EMQX_API_KEY, and EMQX_API_SECRET pointing to your EMQX instance.
3. Add the server definition to claude_desktop_config.json under mcpServers.
4. Issue MCP tool calls such as list_mqtt_clients, get_mqtt_client, kick_mqtt_client, or publish_mqtt_message from an LLM or compatible client.

Key features of Emqx Mcp Server

• Client Management: list all connected clients with pagination and extensive filters (node, client ID, username, IP, connection state, etc.).
• Client Detail Retrieval: fetch full metadata for a specific client ID.
• Connection Control: disconnect (kick) a client remotely.
• Message Publishing: send arbitrary payloads to any MQTT topic, choose QoS 0‑2, and optional retain flag.
• Flexible Deployment: available as Docker image, Smithery package, or source code run via uv.

Use cases of Emqx Mcp Server

• Operational monitoring: LLM‑driven dashboards that query active clients and connection health.
• Automated device management: automatically disconnect stale or misbehaving IoT devices.
• Dynamic messaging: generate content (e.g., alerts, notifications, poems) via an AI model and publish it to MQTT topics.
• Support for CI/CD: integrate broker checks into deployment pipelines using the MCP tools.

FAQ from the Emqx Mcp Server

• What MQTT versions are supported?
  The server works with EMQX v5 APIs, which support MQTT 3.1, 3.1.1, and 5.0.
• Do I need a paid EMQX Cloud plan?
  No. A free serverless deployment is sufficient for testing; dedicated or self‑hosted instances are optional for production.
• How are authentication credentials supplied?
  Via environment variables EMQX_API_KEY and EMQX_API_SECRET. They are passed to the EMQX Management API.
• Can I change the default pagination limits?
  Yes, the limit parameter of list_mqtt_clients can be set up to 10,000.
• Is TLS required?
  The API URL should use https:// when connecting to EMQX Cloud; self‑hosted setups may use HTTP as configured.

EMQX MCP Server

A Model Context Protocol (MCP) server implementation that provides EMQX MQTT broker interaction. Enabling MCP clients to interact with the 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, you need to set up an EMQX cluster with properly configured API Key and client authentication. There are several options:

1. EMQX Cloud Serverless Deployment:

• The easiest way to get started with.
• Obtain a free serverless deployment from EMQX Cloud
• Sign up at EMQX Cloud Serverless

2. EMQX Cloud Dedicated Deployment:

• Provides dedicated resources for production workloads
• Offers enhanced performance, reliability, and customization options
• Supports various cloud providers (AWS, GCP, Azure)
• Includes professional SLA and support
• Create a deployment at EMQX Cloud Dedicated

3. Self-hosted EMQX Platform:

• Download and deploy EMQX Platform locally
• Follow installation instructions at EMQX Platform

Running locally with the Claude Desktop App

Option 1: Installing via Smithery

To install emqx-mcp-server for Claude Desktop automatically via Smithery:

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

Option 2: Docker

1. Install Claude Desktop App if you haven't done so 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"
         ]
       }
     }
   }
   

   Note: Update the env variables:EMQX_API_URL, EMQX_API_KEY, EMQX_API_SECRET

4. Open or Restart Claude Desktop App

5. Try asking Claude to do something with the MQTT broker (e.g. ask it to publish an MQTT message to a topic).

Option 3: Manual Installation

First, ensure you have the uv executable installed. If not, you can install it by following the instructions here.

1. Install Claude Desktop App if you haven't done so yet.
2. Clone this repository.
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": "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>"
         }
       }
     }
   }
   

   Note: Make sure to update path/to/repo/src/emqx_mcp_server to the actual path and modify the environment variables EMQX_API_URL, EMQX_API_KEY, and EMQX_API_SECRET to match your EMQX instance.
4. Open or Restart Claude Desktop App
5. Try asking Claude to do something with the MQTT broker (e.g. ask it to publish an MQTT message to a topic).

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

License

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