MQTT MCP Server

A Model Context Protocol (MCP) server that enables sending MQTT messages to configured brokers. Perfect for integrating MQTT messaging capabilities into Claude Code and other MCP-compatible applications.

Features

• 🚀 Easy Installation: Install directly via npm/npx
• 🔗 Multiple Brokers: Connect to multiple MQTT brokers simultaneously
• 📊 Flexible Messaging: Support for JSON and string message formats
• ⚙️ Configurable QoS: Quality of Service levels 0, 1, and 2
• 🔒 Secure: Environment variable configuration for credentials
• 🛠️ Runtime Management: Add/remove brokers dynamically

Quick Start

For Claude Code Users

claude mcp add mqtt -s user -- npx -y @brightlightrx/mqtt-mcp

For Claude Desktop Users

Add to your MCP settings file:

{
  "mcpServers": {
    "mqtt": {
      "command": "npx",
      "args": ["-y", "@brightlightrx/mqtt-mcp"],
      "env": {
        "MQTT_BROKER_URL": "mqtt://localhost:1883",
        "MQTT_USERNAME": "your_username",
        "MQTT_PASSWORD": "your_password"
      }
    }
  }
}

Configuration

Environment Variables

Configure brokers using environment variables:

# Default broker
MQTT_BROKER_URL=mqtt://localhost:1883
MQTT_USERNAME=myuser
MQTT_PASSWORD=mypass
MQTT_CLIENT_ID=mqtt-mcp-client

# Additional brokers (up to 10)
MQTT_BROKER_1_ID=production
MQTT_BROKER_1_URL=mqtts://prod.example.com:8883
MQTT_BROKER_1_USERNAME=produser
MQTT_BROKER_1_PASSWORD=prodpass

MQTT_BROKER_2_ID=staging
MQTT_BROKER_2_URL=mqtt://staging.example.com:1883

MCP Client Configuration

Configuration File Locations

Claude Code:

• macOS: ~/Library/Application Support/Claude Code/claude_code_mcp_settings.json
• Windows: %APPDATA%/Claude Code/claude_code_mcp_settings.json
• Linux: ~/.config/claude-code/claude_code_mcp_settings.json

Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Example with Multiple Brokers

{
  "mcpServers": {
    "mqtt": {
      "command": "npx",
      "args": ["-y", "@brightlightrx/mqtt-mcp"],
      "env": {
        "MQTT_BROKER_URL": "mqtt://localhost:1883",
        "MQTT_USERNAME": "local_user",
        "MQTT_PASSWORD": "local_pass",
        "MQTT_BROKER_1_ID": "production",
        "MQTT_BROKER_1_URL": "mqtts://prod.example.com:8883",
        "MQTT_BROKER_1_USERNAME": "prod_user",
        "MQTT_BROKER_1_PASSWORD": "prod_pass"
      }
    }
  }
}

Installation with Environment Variables

You can set environment variables during installation:

MQTT_BROKER_URL=mqtt://localhost:1883 MQTT_USERNAME=user MQTT_PASSWORD=pass claude mcp add mqtt -s user -- npx -y @brightlightrx/mqtt-mcp

Testing the Installation

After installation, test it in Claude Code:

Please list all available MQTT brokers.

Available Tools

mqtt_publish

Publish a message to an MQTT topic.

Parameters:

• broker_id (string): ID of the MQTT broker to use
• topic (string): MQTT topic to publish to
• message (string|object): Message to publish (string or JSON object)
• qos (number, optional): Quality of Service level (0, 1, or 2) - default: 0
• retain (boolean, optional): Whether to retain the message on the broker - default: false

Example:

{
  "broker_id": "default",
  "topic": "sensors/temperature",
  "message": {"value": 23.5, "unit": "celsius", "timestamp": "2025-01-13T10:30:00Z"},
  "qos": 1,
  "retain": true
}

mqtt_add_broker

Add a new MQTT broker configuration at runtime.

Parameters:

• id (string): Unique identifier for the broker
• url (string): MQTT broker URL (e.g., mqtt://localhost:1883)
• username (string, optional): Username for authentication
• password (string, optional): Password for authentication
• client_id (string, optional): MQTT client ID

Example:

{
  "id": "test-broker",
  "url": "mqtt://test.example.com:1883",
  "username": "testuser",
  "password": "testpass",
  "client_id": "mcp-test-client"
}

mqtt_list_brokers

List all configured MQTT brokers and their connection status.

Parameters: None

Returns: JSON array with broker IDs and connection status.

Usage Examples

Using with Claude Code

Once configured, you can use natural language in Claude Code to send MQTT messages:

Example conversations:

You: "Send a test message to the topic 'sensors/test' using the default broker"

Claude Code will use: mqtt_publish with broker_id="default", topic="sensors/test", message="test message"

You: "Publish temperature data: 23.5°C and humidity 65% to the IoT topic on the production broker"

Claude Code will use: mqtt_publish with structured JSON data

You: "Add a new MQTT broker for my local testing with URL mqtt://192.168.1.100:1883"

Claude Code will use: mqtt_add_broker to configure the new connection

You: "Configure an MQTT broker with the data in .env and send 'I'm Here' to topic 'test'"

Claude Code will:
1. Read .env file to get broker configuration
2. Add broker using mqtt_add_broker with credentials from .env  
3. Publish "I'm Here" message to "test" topic using mqtt_publish

Direct Tool Usage Examples

Basic Message Publishing

// Publish a simple string message
{
  "broker_id": "default",
  "topic": "test/message", 
  "message": "Hello MQTT!"
}

// Publish JSON data
{
  "broker_id": "default",
  "topic": "devices/sensor1",
  "message": {
    "temperature": 25.3,
    "humidity": 60.2,
    "timestamp": "2025-01-13T10:30:00Z"
  }
}

High QoS Publishing

{
  "broker_id": "production",
  "topic": "critical/alerts",
  "message": {"alert": "Temperature threshold exceeded", "level": "warning"},
  "qos": 2,
  "retain": true
}

Runtime Broker Configuration

// Add a new broker
{
  "id": "iot-platform",
  "url": "mqtts://iot.example.com:8883",
  "username": "device123",
  "password": "secret"
}

// Use the new broker
{
  "broker_id": "iot-platform",
  "topic": "devices/status",
  "message": {"status": "online", "battery": 85}
}

Development

For local development and contributions:

# Clone the repository
git clone https://github.com/brightlightrx/mqtt-mcp.git
cd mqtt-mcp

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Type check
npm run typecheck

# Lint code
npm run lint

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Protocol Support

• MQTT 3.1.1 and 5.0
• TCP, TLS, and WebSocket transports
• QoS levels 0, 1, and 2
• Message retention
• Authentication (username/password)

Error Handling

The server provides detailed error messages for:

• Connection failures
• Authentication errors
• Publishing failures
• Invalid broker configurations
• Network timeouts

Security Notes

• Store sensitive credentials in environment variables
• Use TLS/SSL for production brokers (mqtts://)
• Implement proper access controls on your MQTT brokers
• Consider using client certificates for enhanced security