MQTT-Bridge

MQTT-Bridge provides MQTT communication capabilities for Large Language Models and other clients. It enables connections to MQTT brokers, publishing and subscribing to topics, and managing real-time messaging workflows.

Features

• MQTT Broker Connection: Connect to any MQTT broker with authentication support
• Message Publishing: Publish messages to topics with configurable QoS and retain settings
• Topic Subscription: Subscribe to topics with wildcard support (+ and #)
• Connection Management: Manage multiple concurrent MQTT connections
• Message Monitoring: Track and analyze received messages
• Real-time Updates: Live message reception and connection status monitoring
• Subscription Persistence: Maintain subscriptions across server restarts

Components

Resources

MQTT-Bridge provides these resources:

• Connection Status: Real-time status and details for each MQTT connection
• Message History: Recent MQTT messages with filtering capabilities

Prompts

MQTT-Bridge offers intelligent prompts for:

• mqtt-connection-status: Get formatted status of all MQTT connections
• mqtt-message-analysis: Analyze recent MQTT messages with topic filtering

Tools

MQTT-Bridge implements these MQTT tools:

1. mqtt-connect: Connect to an MQTT broker

   • Supports authentication (username/password)
   • Configurable client ID, keep-alive, and port settings
   • Automatically restores saved subscriptions

2. mqtt-disconnect: Disconnect from an MQTT broker

3. mqtt-publish: Publish messages to topics

   • Configurable QoS levels (0, 1, 2)
   • Retain message support

4. mqtt-subscribe: Subscribe to topics

   • Wildcard support (+ for single level, # for multi-level)
   • Configurable QoS levels
   • Subscriptions are persisted automatically

5. mqtt-unsubscribe: Unsubscribe from topics

   • Automatically updates persistence storage

6. mqtt-list-connections: List all connections and their status

7. mqtt-get-messages: Retrieve recent messages with optional filtering

8. mqtt-get-persistent-subscriptions: Retrieve persisted subscription information

   • View all subscriptions across connections
   • Filter by connection ID
   • Shows topic and QoS information

9. mqtt-delete-subscription: Delete specific subscriptions from persistence

   • Delete from specific connection or all connections
   • Updates runtime tracking for active connections

10. mqtt-delete-all-subscriptions: Delete all persistent subscriptions

    • Nuclear option with confirmation required
    • Completely clears subscription persistence

Installation

Prerequisites

• Python 3.12 or higher
• uv package manager (recommended) or pip

Setup

1. Clone or download this repository
2. Install dependencies:

   uv sync --dev --all-extras
   

Alternatively with pip:

pip install -e .

Configuration

Claude Desktop

Add this configuration to your Claude Desktop config file:

MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mqtt-bridge": {
      "command": "python",
      "args": ["-m", "mqtt_bridge.server"]
    }
  }
}

Project Structure

src/
  mqtt_bridge/
    __init__.py
    server.py                    # Main server implementation
    subscription_persistence.py  # Subscription persistence implementation
.github/
  copilot-instructions.md        # GitHub Copilot workspace instructions
.vscode/
  mcp.json                       # VS Code MCP configuration
  tasks.json                     # Build and run tasks

Subscription Persistence

The server implements subscription persistence to maintain MQTT subscriptions across server restarts:

Features

• Automatically saves subscriptions to disk when they are created or removed
• Restores subscriptions when connections are re-established
• Preserves QoS levels for each subscription
• Gracefully handles shutdown to ensure latest subscription state is saved

Configuration

Subscription persistence can be configured via environment variables:

Variable	Description	Default
MQTT_BRIDGE_PERSISTENCE_DIR	Directory for persistence files	~/.mqtt-bridge
MQTT_BRIDGE_SUBSCRIPTIONS_FILE	Filename for subscriptions	subscriptions.json

Storage Format

Subscriptions are stored in a JSON file with the following structure:

{
  "connection_id1": [
    {"topic": "topic1", "qos": 0},
    {"topic": "topic2", "qos": 1}
  ],
  "connection_id2": [
    {"topic": "topic3", "qos": 2}
  ]
}

Testing

The scripts/test_subscription_persistence.py script can be used to test the subscription persistence functionality.

Subscription Management

The server provides advanced subscription management capabilities:

Viewing Subscriptions

Use the mqtt-get-persistent-subscriptions tool to view all persistent subscriptions:

Show me all persistent MQTT subscriptions

Filter by connection ID:

Show the persistent subscriptions for connection "my-connection"

Deleting Subscriptions

Delete a specific subscription from all connections:

Delete subscription for topic "sensors/temperature"

Delete a subscription from a specific connection:

Delete the "sensors/temperature" subscription from connection "my-connection"

Nuclear Option

Delete all persistent subscriptions (requires confirmation):

Delete all persistent subscriptions

pyproject.toml # Project configuration README.md # This file

### Running the Server

For development:

```bash
uv run python -m mqtt_bridge.server

For production:

python -m mqtt_bridge.server

Testing MQTT Functionality

You can test the server with public MQTT brokers:

• test.mosquitto.org: Public test broker (port 1883)
• broker.emqx.io: Public test broker (port 1883)
• broker.hivemq.com: Public test broker (port 1883)

Debugging

The server logs to stderr, which you can monitor for debugging:

• Connection events
• Message reception
• Error conditions

Security Considerations

• Use secure MQTT brokers (TLS) in production
• Implement proper authentication credentials
• Consider message encryption for sensitive data
• Monitor and limit message rate for public brokers

License

MIT two-clause license applies to this project.

Contributing

1. Follow the MCP server development guidelines
2. Ensure all MQTT operations handle errors gracefully
3. Add tests for new functionality
4. Update documentation for new features

Support

For issues and questions:

• Check the MCP documentation: https://modelcontextprotocol.io/
• Review MQTT protocol specifications: https://mqtt.org/
• Test with public MQTT brokers before reporting connectivity issues

Development

Building and Publishing

To prepare the package for distribution:

1. Sync dependencies and update lockfile:

uv sync

2. Build package distributions:

uv build

This will create source and wheel distributions in the dist/ directory.

Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we recommend using the MCP Inspector.

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.