The emqx-mcp-server
allows you to interact with EMQX MQTT brokers through Model Context Protocol (MCP), providing client management and message publishing capabilities.
MQTT Client Management:
List connected clients with filtering options (paging, limits, node, client ID, username, IP address, connection state, clean start flag, protocol version, and fuzzy matching)
Retrieve detailed information about specific clients by client ID
Disconnect (kick) problematic or stale clients from the broker
MQTT Message Publishing:
Publish messages to any MQTT topics with customizable QoS levels (0, 1, or 2)
Support for message retention and custom payloads
Allows interaction with MQTT clusters on EMQX Cloud or self-hosted clusters, enabling clients to list connected MQTT clients, retrieve client information, disconnect clients, and publish messages to MQTT topics
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:
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
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
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:
Option 2: Docker
Install Claude Desktop App if you haven't done so yet.
Pull the image:
docker pull benniuji/emqx-mcp-serverAdd 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
Open or Restart Claude Desktop App
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.
Install Claude Desktop App if you haven't done so yet.
Clone this repository.
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 variablesEMQX_API_URL
,EMQX_API_KEY
, andEMQX_API_SECRET
to match your EMQX instance.Open or Restart Claude Desktop App
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:
LLM:
User:
LLM:
User:
LLM:
User:
LLM
License
This project is licensed under the Apache License Version 2.0 - see the LICENSE file for details.
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A Model Context Protocol (MCP) server implementation that provides EMQX MQTT broker interaction.
Related Resources
Related MCP Servers
- AsecurityAlicenseAqualityA beginner-friendly Model Context Protocol (MCP) server that helps users understand MCP concepts, provides interactive examples, and lists available MCP servers. This server is designed to be a helpful companion for developers working with MCP. Also comes with a huge list of servers you can install.Last updated -3863Apache 2.0
- -securityAlicense-qualityMCP Server simplifies the implementation of the Model Context Protocol by providing a user-friendly API to create custom tools and manage server workflows efficiently.Last updated -04MIT License
- AsecurityAlicenseAqualityA Model Context Protocol (MCP) server designed to easily dump your codebase context into Large Language Models (LLMs).Last updated -1182Apache 2.0
- -securityAlicense-qualityAn implementation of the Model Context Protocol (MCP) server that enables multiple clients to connect simultaneously and handles basic context management and messaging with an extendable architecture.Last updated -MIT License