Coreflux MQTT MCP Server

How to use

Connect an MCP client to manage MQTT topics, invoke Coreflux models and actions, and leverage automation features. Start by configuring the server with your MQTT broker, TLS certificates, and Copilot API key if you plan to use AI-assisted generation. Use the provided tools to check broker health, publish to topics, and run or test actions and rules. You can drive operations from an MCP client, CLI, or the Claude integration, then monitor health and performance through the built-in health checks and logging.

How to install

Prerequisites: Python 3.11 or higher, Docker (optional for containerized deployment), access to a Coreflux MQTT broker, and a Copilot API key if you want AI assistance.

# Option 1: Docker Deployment (Recommended)

# Clone the project and configure
git clone https://github.com/CorefluxCommunity/Coreflux-MQTT-MCP-Server.git
cd Coreflux-MQTT-MCP-Server
cp .env.example .env
# Edit .env with your configuration

docker-compose up -d

Option 2: Development Installation

# Clone and setup
git clone https://github.com/CorefluxCommunity/Coreflux-MQTT-MCP-Server.git
cd Coreflux-MQTT-MCP-Server

# Install dependencies
pip install -r requirements.txt
# For development
pip install -r requirements-dev.txt

# Configure environment
python setup_assistant.py  # Interactive configuration
# OR
cp .env.example .env && nano .env  # Manual configuration

# Validate and test
make validate  # Validate configuration
make test      # Run tests

# Start the server
python server.py
# OR
make run

Configuration and runtime settings

Set up an interactive configuration to wire TLS, MQTT, and API integration. You can also prepare an environment file with the required variables.

# Interactive setup
python setup_assistant.py

# Environment file example
# Copy and edit
cp .env.example .env
nano .env

Configuring connection details for Claude and MCP clients

Integrate the MCP server with Claude Desktop or via environment variables to enable automated workflows. The server exposes a local stdio interface-based command to run the server script with specific environment settings.

{
  "mcpServers": {
    "coreflux": {
      "command": "python",
      "args": ["/path/to/your/server.py"],
      "env": {
        "MQTT_BROKER": "your-broker-host.com",
        "MQTT_PORT": "8883",
        "MQTT_USER": "your-username",
        "MQTT_PASSWORD": "your-password",
        "MQTT_USE_TLS": "true",
        "DO_AGENT_API_KEY": "your-copilot-api-key"
      }
    }
  }
}

Security, TLS, and logging

TLS encryption is used to secure MQTT connections. The server also sanitizes inputs and logs sensitive data securely. Use the interactive setup to configure TLS certificates and CA files as needed.

# TLS-related env samples (in .env or Claude config)
MQTT_USE_TLS=true
MQTT_CA_CERT=/path/to/ca.crt
MQTT_CERT_FILE=/path/to/client.crt
MQTT_KEY_FILE=/path/to/client.key

Monitoring, health checks, and troubleshooting

You have built-in health checks and monitoring for broker connectivity, message processing, and resource usage. Use the health-check utilities to verify status and to troubleshoot broker reachability or authentication issues.

# Manual health check
python server.py --health-check

# Claude can also trigger a health check with a natural-language request like:
"Please run a comprehensive health check on the Coreflux MCP server"

Development & testing

Developers can run unit and integration tests, format code, lint, and perform security checks. A complete development workflow is provided to set up the environment and run quality checks.

# Development workflow
make dev-setup     # Set up complete development environment
make validate      # Validate configuration
make run           # Start the server with validation
make run-debug     # Start server in debug mode

# Testing and quality
make test          # Run all tests
make test-coverage # Run tests with coverage
make quality-check # Run all quality checks

Available tools and endpoints

The MCP server exposes a set of tools for Coreflux MQTT interactions, Copilot AI assistance, and system health. Below are representative tool names and purposes that you can invoke from your MCP client or Claude integration.

Examples of configuring and starting in Docker (quick reference)

# Docker quick start
git clone https://github.com/CorefluxCommunity/Coreflux-MQTT-MCP-Server.git
cd Coreflux-MQTT-MCP-Server
cp .env.example .env
nano .env  # configure settings

docker-compose up -d

publish_to_coreflux

Publish messages to MQTT topics with QoS and retention options

get_broker_info

Get detailed information about the MQTT broker connection

copilot_assist

Query the Coreflux Copilot AI for automation assistance and code generation

comprehensive_health_check

Perform detailed health checks of all system components