domotz-mcp

Domotz MCP Server

An MCP (Model Context Protocol) server for interacting with the Domotz API, BMS (Building Management System) controllers, MQTT brokers, and Home Assistant. This server provides comprehensive tools for IoT device management, monitoring, and control.

IoT Integration Features

BMS Integration (Experimental)

The BMS (Building Management System) integration extends the base Domotz MCP functionality for comprehensive IoT exploration and management.

Current Status:

• HTTP/HTTPS protocols are fully functional for web-based BMS interfaces
• BACnet and Modbus protocol support is included but requires further development
• The BMS tools can discover and monitor data points from various controller types

MQTT Integration

Full MQTT broker support for IoT device communication:

• Connect to any MQTT broker (local or cloud-based)
• Subscribe to topics for real-time data monitoring
• Publish messages to control IoT devices
• Support for QoS levels and retained messages

Home Assistant Integration

Direct integration with Home Assistant for smart home control:

• Discover all entities, devices, and areas
• Control lights, switches, climate, and more
• Real-time state monitoring
• Support for complex service calls

Installation

npm install -g domotz-mcp

Configuration

Environment Variables

Required for Domotz:

• DOMOTZ_API_KEY: Your Domotz API key
• DOMOTZ_API_ENDPOINT: The Domotz API endpoint URL

Optional for MQTT:

• MQTT_BROKER_URL: Default MQTT broker URL
• MQTT_USERNAME: Default MQTT username
• MQTT_PASSWORD: Default MQTT password

Optional for Home Assistant:

• HA_URL: Default Home Assistant URL
• HA_ACCESS_TOKEN: Default Home Assistant long-lived access token

Usage

With Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Complete Configuration (All Optional Parameters)

{
  "mcpServers": {
    "domotz": {
      "command": "npx",
      "args": ["domotz-mcp"],
      "env": {
        "DOMOTZ_API_KEY": "your-domotz-api-key-here",
        "DOMOTZ_API_ENDPOINT": "https://api-eu-west-1-cell-1.domotz.com/public-api/v1/",
        "MQTT_BROKER_URL": "mqtt://your-mqtt-broker:1883",
        "MQTT_USERNAME": "your-mqtt-username",
        "MQTT_PASSWORD": "your-mqtt-password",
        "HA_URL": "http://homeassistant.local:8123",
        "HA_ACCESS_TOKEN": "your-home-assistant-long-lived-token"
      }
    }
  }
}

Minimal Configuration (Domotz Only)

{
  "mcpServers": {
    "domotz": {
      "command": "npx",
      "args": ["domotz-mcp"],
      "env": {
        "DOMOTZ_API_KEY": "your-api-key-here",
        "DOMOTZ_API_ENDPOINT": "https://api-eu-west-1-cell-1.domotz.com/public-api/v1/"
      }
    }
  }
}

Direct Usage

All Environment Variables

# Required for Domotz
export DOMOTZ_API_KEY="your-api-key-here"
export DOMOTZ_API_ENDPOINT="https://api-eu-west-1-cell-1.domotz.com/public-api/v1/"

# Optional for MQTT
export MQTT_BROKER_URL="mqtt://localhost:1883"
export MQTT_USERNAME="your-mqtt-username"
export MQTT_PASSWORD="your-mqtt-password"

# Optional for Home Assistant
export HA_URL="http://homeassistant.local:8123"
export HA_ACCESS_TOKEN="your-home-assistant-token"

npx domotz-mcp

Minimal Setup (Domotz only)

export DOMOTZ_API_KEY="your-api-key-here"
export DOMOTZ_API_ENDPOINT="https://api-eu-west-1-cell-1.domotz.com/public-api/v1/"
npx domotz-mcp

Available Tools

1. get_all_agents

Get a list of all Domotz agents.

Parameters:

• page_size (string): Number of agents per page (1-100)
• page_number (string): Page number (0-based)

2. get_agent

Get details of a specific Domotz agent.

Parameters:

• agent_id (number): The ID of the agent to retrieve

3. bind_webhook

Bind a webhook to a Domotz agent for receiving events.

Parameters:

• agent_id (number): The ID of the agent to bind the webhook to
• webhook_url (string): The webhook URL to receive events
• events (array, optional): Array of event types to subscribe to (defaults to all events)

4. get_domotz_data

Fetch data from the Domotz API using the configured endpoint and API key.

Parameters:

• endpoint (string): The API endpoint path (e.g., 'agents', 'devices', etc.)
• method (string): HTTP method to use (GET, POST, PUT, DELETE)
• params (string, optional): Query parameters for the request
• data (string, optional): Request body data for POST/PUT requests

5. bms_connect

Connect to BMS controllers to retrieve data points and system information.

Parameters:

• ip (string): IP address of the BMS controller
• port (string, optional): Port number (default: "80")
• protocol (string, optional): Connection protocol - 'http', 'https', 'bacnet', 'modbus' (default: "http")
  • *Note: BACnet and Modbus protocols are experimental and require further development
• username (string, optional): Authentication username
• password (string, optional): Authentication password

Supported BMS Types:

• Trend Controls
• Honeywell
• Johnson Controls
• Generic HTTP/HTTPS interfaces

6. bms_monitor

Provides continuous monitoring of BMS controller data points with historical tracking.

Parameters:

• ip (string): IP address of the BMS controller
• port (string, optional): Port number (default: "80")
• protocol (string, optional): 'http' or 'https' (default: "http")
• username (string, optional): Authentication username
• password (string, optional): Authentication password
• interval (string, optional): Monitoring interval in seconds (default: "60")
• data_points (array, optional): Array of specific data point names to monitor

Features:

• Continuous data collection at specified intervals
• Historical data storage (last 1000 data points)
• Automatic alarm detection based on thresholds
• Status tracking (ok, warning, error) for each data point
• System availability monitoring

7. mqtt_connect

Connect to an MQTT broker for IoT device communication.

Parameters:

• broker_url (string): MQTT broker URL (e.g., mqtt://localhost, ws://broker.hivemq.com)
• client_id (string, optional): Client ID for the connection (auto-generated if not provided)
• username (string, optional): Username for authentication
• password (string, optional): Password for authentication
• port (string, optional): Port number (default: "1883" for mqtt, "8083" for ws)
• clean_session (boolean, optional): Start with clean session (default: true)
• keepalive (string, optional): Keepalive interval in seconds (default: "60")

8. mqtt_subscribe

Subscribe to MQTT topics to receive messages from IoT devices.

Parameters:

• connection_id (string): The connection ID from mqtt_connect
• topic (string): MQTT topic to subscribe to (supports wildcards: + and #)
• qos (number, optional): Quality of Service level (0, 1, or 2, default: 0)
• duration (string, optional): Duration to listen in seconds (default: "10")

9. mqtt_publish

Publish messages to MQTT topics to control IoT devices.

Parameters:

• connection_id (string): The connection ID from mqtt_connect
• topic (string): MQTT topic to publish to
• message (string): Message payload (can be JSON string for complex data)
• qos (number, optional): Quality of Service level (0, 1, or 2, default: 0)
• retain (boolean, optional): Retain message on broker (default: false)

10. ha_discover

Discover entities and devices in Home Assistant.

Parameters:

• ha_url (string): Home Assistant URL (e.g., http://homeassistant.local:8123)
• access_token (string): Long-lived access token from Home Assistant
• entity_type (string, optional): Filter by entity type (e.g., light, switch, sensor, climate)

11. ha_control

Control Home Assistant entities (lights, switches, climate, etc.).

Parameters:

• ha_url (string): Home Assistant URL
• access_token (string): Long-lived access token from Home Assistant
• entity_id (string): Entity ID to control (e.g., light.living_room, switch.garage)
• action (string): Action to perform (turn_on, turn_off, toggle, set_temperature, etc.)
• service_data (string, optional): Additional service data as JSON string

Development

Building

npm install
npm run build

Testing

export DOMOTZ_API_KEY="your-api-key"
export DOMOTZ_API_ENDPOINT="your-endpoint"
node dist/index.js

Examples

Using Domotz Tools

# Get all agents
{
  "tool": "get_all_agents",
  "parameters": {
    "page_size": "50",
    "page_number": "0"
  }
}

# Get devices for a specific agent
{
  "tool": "get_domotz_data",
  "parameters": {
    "endpoint": "agents/12345/devices",
    "method": "GET"
  }
}

Using BMS Tools

# Connect to a BMS controller
{
  "tool": "bms_connect",
  "parameters": {
    "ip": "192.168.1.100",
    "port": "80",
    "protocol": "http"
  }
}

# Monitor BMS data points
{
  "tool": "bms_monitor",
  "parameters": {
    "ip": "192.168.1.100",
    "interval": "30",
    "data_points": ["temperature", "humidity", "pressure"]
  }
}

MQTT Examples

# Connect to MQTT broker
{
  "tool": "mqtt_connect",
  "parameters": {
    "broker_url": "mqtt://test.mosquitto.org",
    "client_id": "domotz_mcp_client"
  }
}

# Subscribe to sensor data
{
  "tool": "mqtt_subscribe",
  "parameters": {
    "connection_id": "domotz_mcp_client",
    "topic": "sensors/+/temperature",
    "duration": "30"
  }
}

# Control a device
{
  "tool": "mqtt_publish",
  "parameters": {
    "connection_id": "domotz_mcp_client",
    "topic": "devices/light/control",
    "message": "{\"state\": \"on\", \"brightness\": 80}"
  }
}

Home Assistant Examples

# Discover all devices
{
  "tool": "ha_discover",
  "parameters": {
    "ha_url": "http://192.168.1.100:8123",
    "access_token": "your-long-lived-token"
  }
}

# Turn on a light
{
  "tool": "ha_control",
  "parameters": {
    "ha_url": "http://192.168.1.100:8123",
    "access_token": "your-long-lived-token",
    "entity_id": "light.living_room",
    "action": "turn_on",
    "service_data": "{\"brightness\": 255, \"color_name\": \"blue\"}"
  }
}

Troubleshooting

Common Issues

• 401 Invalid API Key: Ensure your DOMOTZ_API_KEY environment variable is set correctly
• Connection timeouts: Check network connectivity and firewall settings
• BMS connection failures:
  • Verify the IP address and port are correct
  • Check if authentication is required
  • Ensure the protocol matches your BMS type
• Tool not found: Make sure you're using the exact tool name as documented

BMS-Specific Issues

• No data points found: The BMS might use a different web interface path. The tool attempts multiple common paths automatically.
• Authentication errors: Some BMS controllers require specific credentials. Use the username and password parameters.
• Protocol mismatch: Try different protocols (http, https) if connection fails.
• BACnet/Modbus connections: These protocols are experimental and may not work as expected. Use HTTP/HTTPS for reliable connections.

Changelog

v0.0.23 (Current)

• Fixed tool names and availability issues
• Rebuilt package to ensure all tools are properly exposed
• Verified Home Assistant and MQTT tool functionality

v0.0.22

• Updated documentation with complete configuration examples
• Added environment variable support for MQTT and Home Assistant

v0.0.21

• Added MQTT broker integration tools (connect, subscribe, publish)
• Added Home Assistant integration (discovery and control)
• Extended IoT device management capabilities
• Support for real-time data streaming via MQTT

v0.0.20

• Updated documentation for BMS features
• Added IoT-related keywords
• Clarified experimental status of BACnet/Modbus

v0.0.19

• Added BMS connection and monitoring tools
• Support for multiple BMS controller types
• Historical data tracking for BMS monitoring

v0.0.15

• Fixed MCP protocol compatibility issues
• Added support for API key as command-line argument
• Improved error handling for MCP responses
• Fixed tool discovery for npx usage

v0.0.9

• Added bin field to package.json to enable npx execution
• Fixed package executable configuration

v0.0.8

• Fixed server initialization issue with mcp-framework
• Removed example tool
• Improved error handling

v0.0.7

• Initial release with basic Domotz API integration

License

ISC