emqx

This MCP server provides an interface to manage and interact with EMQX MQTT brokers via the Model Context Protocol. It exposes tooling to list and inspect MQTT clients, kick (disconnect) clients, publish messages to topics, and subscribe to topics via Server-Sent Events (SSE). You can filter clients by node, client ID, username, IP, and connection state, and you can control the QoS and retention of published messages. The subscribe tool streams real-time topic data for a configurable duration, making it useful for monitoring or debugging MQTT activity. To get started, configure the EMQX API URL and credentials in your environment, then run the server (in Docker in this setup) and connect Claude Desktop or your MCP client to the exposed endpoints. The toolset includes list_mqtt_clients, get_mqtt_client, kick_mqtt_client, publish_mqtt_message, and subscribe_mqtt_topic for comprehensive broker management.

Prerequisites:

• Docker installed on your host (or another preferred runtime as configured)
• Access to an EMQX Cloud or self-hosted EMQX cluster with API key and credentials

Installation steps:

1. Ensure Docker is installed and running on your machine.
2. Pull or run the MCP server image with your EMQX credentials:

# Run directly with Docker (example)
docker 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

3. If you need to integrate with Claude Desktop, add the MCP server to your claude_desktop_config.json as shown in the readme, using the docker command and environment variables above, or adapt to your local orchestration.
4. Verify connectivity by issuing a simple prompt to list clients or publish a test message via the MCP interface.

Optional: If you prefer an alternative runtime, you can adapt the configuration to npx/uv/docker as described in the readme, but this guide uses the Docker approach for simplicity.

Tips and notes:

• The subscribe_mqtt_topic tool relies on SSE support from EMQX Cloud deployments. Some self-hosted EMQX setups may not support SSE subscriptions.
• Keep your EMQX_API_URL, EMQX_API_KEY, and EMQX_API_SECRET secure; avoid exposing them in shared configurations.
• When using Docker, the --rm flag ensures the container is removed after execution; remove it if you want to keep containers for debugging.
• The environment variables can be adjusted or extended with additional EMQX-related settings as needed by your deployment.
• If you run into connectivity issues, verify network access from the host to the EMQX API endpoint and confirm that the API port is reachable.
• To upgrade the MCP server image, pull the latest benniuji/emqx-mcp-server image and re-run with the same env vars.