Installation

Installation

mcmqtt is designed for instant execution with zero configuration. Choose the installation method that best fits your workflow.

Recommended: uvx (Instant Execution)

The fastest way to run mcmqtt with no installation required:

# Run mcmqtt directly
uvx mcmqtt

# Run with specific options
uvx mcmqtt --transport http --port 8080

# Add to Claude Code MCP servers
claude mcp add task-buzz "uvx mcmqtt"

Benefits:

• ✅ No installation or setup required
• ✅ Always runs the latest version
• ✅ Isolated execution environment
• ✅ Perfect for testing and development

Traditional Installation

Using uv (Recommended)

# Install mcmqtt
uv add mcmqtt

# Or install globally
uv tool install mcmqtt

# Run mcmqtt
mcmqtt

Using pip

# Install from PyPI
pip install mcmqtt

# Or install from source
pip install git+https://git.supported.systems/MCP/mcmqtt.git

# Run mcmqtt
mcmqtt

Using pipx (Isolated Installation)

# Install in isolated environment
pipx install mcmqtt

# Run mcmqtt
mcmqtt

Development Installation

For contributing to mcmqtt or customizing functionality:

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

# Install in development mode with uv
uv sync --dev

# Or with pip
pip install -e ".[dev]"

# Run tests
pytest

# Run mcmqtt
python -m mcmqtt

Container Deployment

Docker

Run mcmqtt in a container for production deployments:

# Build the image
docker build -t mcmqtt .

# Run basic container
docker run -p 8080:8080 mcmqtt --transport http

# Run with environment configuration
docker run -p 8080:8080 \
  -e MQTT_BROKER_HOST=mqtt.example.com \
  -e MQTT_BROKER_PORT=1883 \
  mcmqtt

Docker Compose

For production deployments with MQTT brokers:

docker-compose.yml

version: '3.8'
services:
  mcmqtt:
    build: .
    ports:
      - "8080:8080"
    environment:
      - MQTT_BROKER_HOST=mosquitto
      - MQTT_BROKER_PORT=1883
    depends_on:
      - mosquitto

  mosquitto:
    image: eclipse-mosquitto:2
    ports:
      - "1883:1883"
    volumes:
      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf

# Start the stack
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs mcmqtt

System Requirements

Minimum Requirements

• Python: 3.11 or higher
• Memory: 256MB RAM
• Storage: 100MB disk space
• Network: Internet connection for PyPI packages

Recommended Specifications

• Python: 3.12+ for best performance
• Memory: 1GB+ RAM for agent swarms
• Storage: 1GB+ for logs and temporary files
• CPU: 2+ cores for concurrent operations

Platform Support

Platform	Support Level	Notes
Linux	✅ Full	Primary development platform
macOS	✅ Full	Intel and Apple Silicon
Windows	✅ Full	WSL2 recommended
Docker	✅ Full	Cross-platform containers

Verification

After installation, verify mcmqtt is working correctly:

# Check version
mcmqtt --version
# or
uvx mcmqtt --version

# Expected output:
# mcmqtt v2025.09.17 - FastMCP MQTT Server

# Test basic functionality
mcmqtt --help

# Start in test mode
mcmqtt --test-mode

MCP Integration

Claude Code Setup

Add mcmqtt to your Claude Code configuration:

# Add mcmqtt as MCP server
claude mcp add task-buzz "uvx mcmqtt"

# Test the connection
claude mcp test task-buzz

# List all MCP servers
claude mcp list

# Expected output:
# ✅ task-buzz: uvx mcmqtt (connected)

Custom MCP Configuration

For advanced setups, create a custom MCP configuration:

{
  "mcpServers": {
    "mcmqtt-prod": {
      "command": "uvx",
      "args": ["mcmqtt", "--broker", "mqtt://prod-broker:1883"],
      "env": {
        "MQTT_CLIENT_ID": "production-client",
        "LOG_LEVEL": "INFO"
      }
    },
    "mcmqtt-dev": {
      "command": "uvx",
      "args": ["mcmqtt", "--transport", "http", "--port", "8080"],
      "env": {
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Environment Configuration

Environment Variables

Configure mcmqtt behavior with environment variables:

# Broker connection
export MQTT_BROKER_HOST="mqtt.example.com"
export MQTT_BROKER_PORT="1883"
export MQTT_USERNAME="username"
export MQTT_PASSWORD="password"

# Client settings
export MQTT_CLIENT_ID="mcmqtt-server"
export MQTT_KEEPALIVE="60"
export MQTT_QOS_DEFAULT="1"

# Server settings
export MCMQTT_TRANSPORT="stdio"  # or "http"
export MCMQTT_PORT="8080"
export LOG_LEVEL="INFO"

# Agent coordination
export AGENT_ISOLATION="container"
export AGENT_MEMORY_LIMIT="512MB"
export AGENT_CPU_LIMIT="0.5"

# Run with environment config
uvx mcmqtt

Configuration File

Create a configuration file for complex setups:

mcmqtt.yaml

server:
  transport: stdio
  port: 8080
  log_level: INFO

mqtt:
  broker:
    host: mqtt.example.com
    port: 1883
    username: user
    password: pass
  client:
    id: mcmqtt-server
    keepalive: 60
    clean_session: true

agents:
  isolation: container
  resources:
    memory: 512MB
    cpu: 0.5
    disk: 1GB
  coordination:
    pattern: worker-pool
    health_check_interval: 30

# Use configuration file
uvx mcmqtt --config mcmqtt.yaml

Troubleshooting Installation

Common Issues

Python Version Error

# Error: Python 3.11+ required
python --version

# Solution: Install Python 3.11+
# On Ubuntu/Debian:
sudo apt update && sudo apt install python3.11

# On macOS:
brew install python@3.11

# On Windows:
# Download from python.org

Permission Errors

# Error: Permission denied
# Solution: Use user installation
pip install --user mcmqtt

# Or use pipx for isolation
pipx install mcmqtt

Network/Firewall Issues

# Error: Connection timeout
# Solution: Check firewall and proxy settings

# Test connectivity
curl -I https://pypi.org/simple/mcmqtt/

# Configure proxy if needed
pip install --proxy http://proxy.example.com:8080 mcmqtt

Missing Dependencies

# Error: ModuleNotFoundError
# Solution: Install with all dependencies
pip install mcmqtt[all]

# Or install specific extras
pip install mcmqtt[dev,test]

Diagnostic Commands

# Check Python environment
python -m mcmqtt --diagnose

# Check MQTT connectivity
uvx mcmqtt --test-mqtt mqtt://test.mosquitto.org:1883

# Check container support
uvx mcmqtt --test-containers

# Generate system report
uvx mcmqtt --system-report

Upgrading

Upgrade with uvx

# uvx automatically uses latest version
uvx mcmqtt  # Always runs latest

Upgrade Traditional Installation

# With uv
uv tool upgrade mcmqtt

# With pip
pip install --upgrade mcmqtt

# With pipx
pipx upgrade mcmqtt

Version Pinning

# Pin to specific version
pip install mcmqtt==2025.09.17

# Or use version constraints
pip install "mcmqtt>=2025.09.17,<2026"

Next Steps

Once mcmqtt is installed:

1. Quick Start - Get running in 2 minutes
2. Configuration - Customize for your needs
3. First Connection - Make your first MQTT connection
4. Agent Coordination - Explore fractal agent capabilities

---

Installation is just the beginning. mcmqtt’s real power emerges when you start coordinating AI agents across distributed systems. 🚀