mcmqtt/README.md

🚀 mcmqtt - FastMCP MQTT Server

The most powerful FastMCP MQTT integration server on the planet 🌍

Enabling MQTT integration for MCP clients with embedded broker support and fractal agent orchestration

✨ Key Features

• 🔥 FastMCP Integration: Native Model Context Protocol server with MQTT tools
• ⚡ Embedded MQTT Brokers: Spawn brokers on-demand with zero configuration
• 🏗️ Modular Architecture: Clean, testable, maintainable codebase
• 🧪 Comprehensive Testing: 70+ tests with 96%+ coverage on core modules
• 🌐 Cross-Platform: Designed for Linux, macOS, and Windows (TODO: Test on additional platforms)
• 🔧 CLI & Programmatic: Use via command line or integrate into your code
• 📡 Real-time Coordination: Perfect for agent swarms and distributed systems

🚀 Quick Start

Installation

# Install from PyPI
pip install mcmqtt

# Or use uv (recommended)
uv add mcmqtt

# Or install directly with uvx
uvx mcmqtt --help

Instant MQTT Magic

# Start FastMCP MQTT server with embedded broker
mcmqtt --transport stdio --auto-broker

# HTTP mode for web integration
mcmqtt --transport http --port 8080 --auto-broker

# Connect to existing broker
mcmqtt --mqtt-host mqtt.example.com --mqtt-port 1883

MCP Integration

Add to your Claude Code MCP configuration:

# Add mcmqtt as an MCP server
claude mcp add task-buzz "uvx mcmqtt --broker mqtt://localhost:1883"

# Test the connection
claude mcp test task-buzz

🛠️ Core Features

🏃‍♂️ FastMCP MQTT Tools

• mqtt_connect - Connect to MQTT brokers
• mqtt_publish - Publish messages with QoS support
• mqtt_subscribe - Subscribe to topics with wildcards
• mqtt_get_messages - Retrieve received messages
• mqtt_status - Get connection and statistics
• mqtt_spawn_broker - Create embedded brokers instantly
• mqtt_list_brokers - Manage multiple brokers

🔧 Embedded Broker Management

from mcmqtt.broker import BrokerManager

# Spawn a broker programmatically
manager = BrokerManager()
broker_info = await manager.spawn_broker(
    name="my-broker",
    port=1883,
    max_connections=100
)

print(f"Broker running at: {broker_info.url}")

📡 MQTT Client Integration

from mcmqtt.mqtt import MQTTClient
from mcmqtt.mqtt.types import MQTTConfig

config = MQTTConfig(
    broker_host="localhost",
    broker_port=1883,
    client_id="my-client"
)

client = MQTTClient(config)
await client.connect()
await client.publish("sensors/temperature", "23.5")

🏗️ Architecture Excellence

This isn't your typical monolithic MQTT library. mcmqtt features a clean modular architecture:

mcmqtt/
├── cli/           # Command-line interface & argument parsing
├── config/        # Environment & configuration management  
├── logging/       # Structured logging setup
├── server/        # STDIO & HTTP server runners
├── mqtt/          # Core MQTT client functionality
├── mcp/           # FastMCP server integration
├── broker/        # Embedded broker management
└── middleware/    # Broker middleware & orchestration

🧪 Testing Excellence

• 70+ comprehensive tests covering all modules
• 96%+ code coverage on refactored components
• Robust mocking for reliable CI/CD
• Edge case coverage for production reliability

🌟 Use Cases

🤖 AI Agent Coordination

Perfect for coordinating Claude Code subagents via MQTT:

# Parent agent publishes tasks
mcmqtt-publish --topic "agents/tasks" --payload '{"task": "analyze_data", "agent_id": "worker-1"}'

# Worker agents subscribe and respond
mcmqtt-subscribe --topic "agents/tasks" --callback process_task

📊 IoT Data Collection

# Collect sensor data
mcmqtt-subscribe --topic "sensors/+/temperature" --format json

# Forward to analytics
mcmqtt-publish --topic "analytics/temperature" --payload "$sensor_data"

🔄 Microservice Communication

# Service mesh communication
mcmqtt --mqtt-host service-mesh.local --client-id user-service

⚙️ Configuration

Environment Variables

export MQTT_BROKER_HOST=localhost
export MQTT_BROKER_PORT=1883
export MQTT_CLIENT_ID=my-client
export MQTT_USERNAME=user
export MQTT_PASSWORD=secret
export MQTT_USE_TLS=true

Command Line Options

mcmqtt --help

Options:
  --transport [stdio|http]     Server transport mode
  --mqtt-host TEXT            MQTT broker hostname
  --mqtt-port INTEGER         MQTT broker port  
  --mqtt-client-id TEXT       MQTT client identifier
  --auto-broker              Spawn embedded broker
  --log-level [DEBUG|INFO|WARNING|ERROR]
  --log-file PATH             Log to file

🚦 Development

Requirements

• Python 3.11+
• UV package manager (recommended)
• FastMCP framework
• Paho MQTT client

Setup

# Clone the repository
git clone https://git.supported.systems/MCP/mcmqtt.git
cd mcmqtt

# Install dependencies
uv sync

# Run tests
uv run pytest

# Build package
uv build

Testing

# Run all tests
uv run pytest tests/

# Run with coverage
uv run pytest --cov=src/mcmqtt --cov-report=html

# Test specific modules
uv run pytest tests/unit/test_cli_comprehensive.py -v

📈 Performance

• Lightweight: Minimal memory footprint
• Fast: Async/await throughout for maximum throughput
• Scalable: Handle thousands of concurrent connections
• Reliable: Comprehensive error handling and retry logic

🤝 Contributing

We love contributions! This project follows the "campground rule" - leave it better than you found it.

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

📄 License

MIT License - see LICENSE for details.

🙏 Credits

Created with ❤️ by Ryan Malloy

Built on the shoulders of giants:

• FastMCP - Modern MCP framework
• Paho MQTT - Reliable MQTT client
• AMQTT - Pure Python MQTT broker

---

Ready to revolutionize your MQTT integration? Install mcmqtt today! 🚀

uvx mcmqtt --transport stdio --auto-broker