MQTT MCP Server

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

1. Build the project:

npm run build

1. 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"

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

"Read the latest messages from sensors/temperature"

1. Check all active subscriptions:

"List my MQTT subscriptions"

1. Unsubscribe when done:

"Unsubscribe from sensors/temperature"

License

MIT