A production-ready Model Context Protocol (MCP) server that connects to Coreflux MQTT brokers and provides Coreflux automation capabilities to Claude and other MCP-compatible AI assistants.
- π MQTT Integration: Seamless connection to Coreflux MQTT brokers with TLS support
- π οΈ Complete Coreflux API: Full access to models, actions, rules, and routes
- π€ AI Code Generation: LOT (Logic Object Tree) code generation via Coreflux Copilot API
- π Dynamic Discovery: Automatic discovery and listing of available actions
- π Production Security: Comprehensive log sanitization and security features
- π³ Docker Ready: Full Docker and Kubernetes deployment support
- βοΈ Easy Setup: Interactive setup assistant for quick configuration
- π Rich Documentation: Built-in LOT language documentation and examples
-
Clone 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
-
Deploy with Docker:
docker-compose up -d
-
Install dependencies:
pip install -r requirements.txt
-
Run setup assistant:
python setup_assistant.py
-
Start the server:
python server.py
For detailed deployment instructions, see DEPLOYMENT.md.
The server includes an interactive setup assistant for easy configuration:
- You need to create an initial configuration (.env file)
- You want to update your existing configuration
- You're experiencing connection issues and need to reconfigure
To run the setup assistant:
python setup_assistant.py
Use the setup assistant when:
- Creating initial configuration (.env file)
- Updating existing configuration
- Experiencing connection issues
- Setting up TLS certificates
The assistant helps configure:
- MQTT broker settings (host, port, credentials)
- TLS configuration and certificates
- Coreflux Copilot API integration
- Logging preferences
-
Create or edit
~/Library/Application Support/Claude/claude_desktop_config.json
(macOS/Linux) or%USERPROFILE%\AppData\Roaming\Claude\claude_desktop_config.json
(Windows) -
Add the following configuration (adjust the paths accordingly):
{ "mcpServers": { "coreflux": { "command": "python", "args": [ "/PATH/TO/server.py", "--mqtt-host", "localhost", "--mqtt-port", "1883", "--mqtt-user", "root", "--mqtt-password", "coreflux", "--mqtt-client-id", "claude-coreflux-client", "--do-agent-api-key", "your_coreflux_copilot_api_key_here" ], "description": "Coreflux MQTT Broker Control", "icon": "π", "env": {} } } }
Note: Instead of passing the API key as a command-line argument, you can set it in the
.env
file for better security.Tip: A sample
claude_desktop_config.json
file is included in this repository that you can use as a starting point. -
Restart Claude Desktop
The server accepts the following command-line arguments. These settings can also be configured via the .env
file using the setup assistant:
Argument | Description | Default |
---|---|---|
--mqtt-host |
MQTT broker address | localhost |
--mqtt-port |
MQTT broker port | 1883 |
--mqtt-user |
MQTT username | - |
--mqtt-password |
MQTT password | - |
--mqtt-client-id |
MQTT client ID | claude-mcp-client |
--mqtt-use-tls |
Enable TLS for MQTT connection | false |
--mqtt-ca-cert |
Path to CA certificate file | - |
--mqtt-client-cert |
Path to client certificate file | - |
--mqtt-client-key |
Path to client key file | - |
--do-agent-api-key |
Coreflux Copilot API key | - |
--log-level |
Logging level (DEBUG/INFO/WARNING/ERROR/CRITICAL) | INFO |
The server includes a request_lot_code
tool that uses the Coreflux Copilot API to generate LOT (Logic Object Tree) code based on natural language prompts. To use this feature, you need to:
- Get an API key from the Coreflux Copilot dashboard
- Set the API key in your
.env
file:DO_AGENT_API_KEY=your_coreflux_copilot_api_key_here
- Or pass it as a command-line argument:
python server.py --do-agent-api-key your_api_key_here
Note: Without the API key, the LOT code generation feature will not work. The setup assistant will prompt you to configure this when you run it.
API Endpoint: The server is pre-configured to connect to the Coreflux Copilot API endpoint. The request format conforms to the chat completions API specification with proper authentication headers.
For production environments, use Docker with proper configuration:
# Copy and customize environment
cp .env.example .env
cp docker-compose.override.yml.example docker-compose.override.yml
# Configure for production
docker-compose up -d
- Log Sanitization: Automatic redaction of sensitive information in logs
- TLS Support: Full TLS encryption for MQTT connections
- Non-root Containers: Docker containers run as non-privileged users
- Secret Management: Environment-based configuration for sensitive data
See SECURITY.md for detailed security guidelines and DEPLOYMENT.md for production deployment instructions.
The server provides tools for common Coreflux commands:
add_rule
: Add a new permission ruleremove_rule
: Remove a permission ruleadd_route
: Add a new route connectionremove_route
: Remove a route connectionadd_model
: Add a new model structureremove_model
: Remove a model structureadd_action
: Add a new action event/functionremove_action
: Remove an action event/functionrun_action
: Run an action event/functionremove_all_models
: Remove all modelsremove_all_actions
: Remove all actionsremove_all_routes
: Remove all routeslist_discovered_actions
: List all discovered Coreflux actionsrequest_lot_code
: Generate LOT code using Coreflux Copilot API based on natural language prompts
The MCP server now starts even if the MQTT broker is not available, allowing you to troubleshoot and configure connections through the MCP tools.
- The server will start successfully even if the MQTT broker is unreachable
- Use the
get_connection_status
tool to check connection health and get troubleshooting guidance - Use the
setup_mqtt_connection
tool to configure a new broker connection without restarting - Use the
check_broker_health
orreconnect_mqtt
tools to test and retry connections
get_connection_status
: Get detailed connection status with troubleshooting guidancesetup_mqtt_connection
: Configure a new MQTT broker connection dynamicallymqtt_connect
: Connect to a specific MQTT broker with custom parameterscheck_broker_health
: Test broker connectivity and attempt reconnectionreconnect_mqtt
: Force reconnection to the configured broker
If you encounter issues:
- Verify your MQTT broker credentials in your Claude configuration
- Ensure the broker is accessible
- Run the setup assistant to verify or update your configuration:
python setup_assistant.py
- Check Claude Desktop logs:
# Check Claude's logs for errors (macOS/Linux) tail -n 20 -f ~/Library/Logs/Claude/mcp*.log # Windows PowerShell Get-Content -Path "$env:USERPROFILE\AppData\Roaming\Claude\Logs\mcp*.log" -Tail 20 -Wait
- Run the server with debug logging:
# Direct execution with debug logging python server.py --mqtt-host localhost --mqtt-port 1883 --log-level DEBUG
- DEPLOYMENT.md - Production deployment guide
- SECURITY.md - Security guidelines and best practices
- MCP Documentation - Official MCP documentation
- Coreflux Platform - Coreflux automation platform
Contributions are welcome! Please read our contributing guidelines and submit pull requests to the development
branch.
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
- π Documentation: Check the README, DEPLOYMENT.md, and SECURITY.md files
- π Issues: Report bugs and feature requests on GitHub
- π¬ Community: Join the Coreflux community for discussions