list_mqtt_clientsLABSCO SUMMARY
Watch a live topic and publish onto it from the same place you are diagnosing the problem.
The timed subscription is what makes this a debugging tool rather than an admin panel: you listen to a topic for a bounded window, see what is actually flowing, and can publish a test message onto it without wiring up a client.
What it is
A server over an EMQX MQTT broker: connected clients listed and inspected, problem clients disconnected, messages published, and topics subscribed to over Server-Sent Events.
What you get
- Connected clients listed with paging, and filters on node, username, client ID, IP address, connection state, clean-start flag and protocol version
- Fuzzy filters on client ID, username and IP for when you only have part of the string
- Full detail on one client
- A client disconnected from the broker
- Messages published to any topic, with a QoS level of 0, 1 or 2 and an option to retain them for new subscribers
- A topic subscribed to for a bounded window, with a cap on how many messages to collect, parsed out of the SSE stream automatically
Requirements
An EMQX cluster you can reach — EMQX Cloud serverless or a self-hosted deployment.
Setup effort
Follow the published steps — docker pull benniuji/emqx-mcp-server
USE CASES
01
Finding out whether a device is actually connected
Filter the client list by client ID or username, then read the full record for the one you found.
02
Seeing what a topic is carrying right now
Subscribe for a bounded window with a message cap and read back what arrived.
03
Testing a subscriber without writing a client
Publish a message at the QoS level the subscriber expects, retained if new subscribers need to see it.
04
Clearing a stale session that is holding a client ID
Find it in the listing, confirm it is the one, and disconnect it from the broker.
05
Auditing what is connected to a node
Filter the client list by node and connection state to see where the load actually sits.
5 tools
Listed in project docs. Your client may show a different list.
get_mqtt_clientkick_mqtt_clientpublish_mqtt_messagesubscribe_mqtt_topicBEFORE YOU INSTALL
What to know first
Tools you get
5 tools named in the project's documentation.
Requires
- EMQX_API_KEY in your environment
- EMQX_API_SECRET in your environment
INSTALLATION
Connect your client
Server setup
Set up an EMQX cluster (EMQX Cloud Serverless / Dedicated, or self-hosted) and create an API Key + Secret
TERMINAL
docker pull benniuji/emqx-mcp-serverAdd the mcpServers block below to claude_desktop_config.json, filling in EMQX_API_URL / EMQX_API_KEY / EMQX_API_SECRET
Open or restart the Claude Desktop App
MCP Clients
Claude Desktop — Docker
CLAUDE DESKTOP — DOCKER · JSON
{
"mcpServers": {
"EMQX_MCP_Server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"EMQX_API_URL=<YOUR_EMQX_CLOUD_URL>:8443/api/v5",
"-e",
"EMQX_API_KEY=<YOUR_EMQX_API_KEY>",
"-e",
"EMQX_API_SECRET=<YOUR_EMQX_API_SECRET>",
"benniuji/emqx-mcp-server"
]
}
}
}Claude Desktop — uv
Clone the repository
This route runs the server from a local copy, with uv installed.
CLAUDE DESKTOP — UV · TERMINAL
git clone https://github.com/Benniu/emqx-mcp-serverAdd to claude_desktop_config.json
<YOUR_PATH_TO_REPO> is the absolute path of the folder you just cloned.
CLAUDE DESKTOP — UV · JSON
{
"mcpServers": {
"EMQX_MCP_Server": {
"command": "uv",
"args": [
"--directory",
"<YOUR_PATH_TO_REPO>/src/emqx_mcp_server",
"run",
"emqx-mcp-server"
],
"env": {
"EMQX_API_URL": "<YOUR_EMQX_CLOUD_URL>:8443/api/v5",
"EMQX_API_KEY": "<YOUR_EMQX_API_KEY>",
"EMQX_API_SECRET": "<YOUR_EMQX_API_SECRET>"
}
}
}
}
