# 🚀 mcmqtt - FastMCP MQTT Server

**The most powerful FastMCP MQTT integration server on the planet** 🌍

[![Version](https://img.shields.io/badge/version-2025.09.17-blue.svg)](https://pypi.org/project/mcmqtt/)
[![Python](https://img.shields.io/badge/python-3.11+-green.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-70%20passing-brightgreen.svg)](#testing)
[![Coverage](https://img.shields.io/badge/coverage-96%25+-brightgreen.svg)](#coverage)

> **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

**Recommended: Use `uvx` for instant execution** (no installation needed):

```bash
# Run directly with uvx (recommended)
uvx mcmqtt --help

# Start STDIO server for MCP clients
uvx mcmqtt

# HTTP mode for web integration  
uvx mcmqtt --transport http --port 8080
```

**If you insist on traditional installation**:

```bash
# Install with uv
uv add mcmqtt

# Or use pip
pip install mcmqtt
```

### Instant MQTT Magic

```bash
# Start FastMCP MQTT server (default STDIO mode) - Just works!
uvx mcmqtt

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

# Connect to existing broker (optional)
uvx mcmqtt --mqtt-host mqtt.example.com --mqtt-port 1883
```

### MCP Integration

Add to your Claude Code MCP configuration:

```bash
# Add mcmqtt as an MCP server (zero configuration!)
claude mcp add task-buzz -- uvx mcmqtt

# 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

```python
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

```python
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:

```bash
# 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

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

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

### 🔄 Microservice Communication

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

## ⚙️ Configuration

### Environment Variables

```bash
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

```bash
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

```bash
# 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

```bash
# 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](LICENSE) for details.

## 🙏 Credits

Created with ❤️ by [Ryan Malloy](mailto:ryan@malloys.us)

Built on the shoulders of giants:
- [FastMCP](https://github.com/jlowin/fastmcp) - Modern MCP framework
- [Paho MQTT](https://github.com/eclipse/paho.mqtt.python) - Reliable MQTT client
- [AMQTT](https://github.com/Yakifo/amqtt) - Pure Python MQTT broker

---

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

```bash
uvx mcmqtt --transport stdio --auto-broker
```