MQTT MCP Server

An MCP (Model Context Protocol) server that enables Cursor to read messages from an MQTT broker.

Features

• Subscribe to MQTT topics (supports wildcards + and #)
• Read buffered messages from subscribed topics
• List active subscriptions
• Configurable message buffer size

Installation

1. Install dependencies:

npm install

2. Build the project:

npm run build

3. Copy .env.example to .env and configure your MQTT broker settings:

cp .env.example .env

Configuration

Edit the .env file with your MQTT broker details:

Variable	Description	Default
MQTT_BROKER_URL	MQTT broker URL (mqtt:// or mqtts://)	mqtt://localhost:1883
MQTT_USERNAME	Username for authentication	(none)
MQTT_PASSWORD	Password for authentication	(none)
MQTT_CLIENT_ID	Client ID for MQTT connection	cursor-mqtt-mcp-{timestamp}
MAX_MESSAGES_PER_TOPIC	Max messages to buffer per topic	100

Cursor Configuration

Add this MCP server to your Cursor settings (.cursor/mcp.json or global settings):

{
  "mcpServers": {
    "mqtt": {
      "command": "node",
      "args": ["C:/path/to/mqtt-mcp/dist/index.js"],
      "env": {
        "MQTT_BROKER_URL": "mqtt://your-broker:1883",
        "MQTT_USERNAME": "your_username",
        "MQTT_PASSWORD": "your_password"
      }
    }
  }
}

Alternatively, if using a .env file in the project directory:

{
  "mcpServers": {
    "mqtt": {
      "command": "node",
      "args": ["C:/path/to/mqtt-mcp/dist/index.js"],
      "cwd": "C:/path/to/mqtt-mcp"
    }
  }
}

Available Tools

mqtt_subscribe

Subscribe to an MQTT topic to start receiving messages.

Parameters:

• topic (required): The MQTT topic to subscribe to
• qos (optional): Quality of Service level (0, 1, or 2). Default: 0

Example:

Subscribe to "sensors/temperature"
Subscribe to "devices/+/status" (single-level wildcard)
Subscribe to "home/#" (multi-level wildcard)

mqtt_unsubscribe

Unsubscribe from an MQTT topic.

Parameters:

• topic (required): The MQTT topic to unsubscribe from

mqtt_read_messages

Read buffered messages from subscribed topics.

Parameters:

• topic (optional): Specific topic to read from. If omitted, reads from all topics
• limit (optional): Maximum messages to return. Default: 10
• clear (optional): Clear buffer after reading. Default: false

mqtt_list_subscriptions

List all active subscriptions and their message counts.

Parameters: None

Usage Example

1. First, subscribe to a topic:

   "Subscribe to the MQTT topic sensors/temperature"

2. Wait for messages to arrive, then read them:

   "Read the latest messages from sensors/temperature"

3. Check all active subscriptions:

   "List my MQTT subscriptions"

4. Unsubscribe when done:

   "Unsubscribe from sensors/temperature"

License

MIT