domotz-mcp/USAGE.md

MCP server for Domotz API and BMS (Building Management System) integration with IoT device monitoring

# Domotz MCP Server Usage Guide

## Installation

```bash
npm install -g domotz-mcp
# or use directly with npx
npx domotz-mcp@latest
```

## Configuration

### Environment Variables

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

**Optional for MQTT:**
```bash
export MQTT_BROKER_URL="mqtt://your-broker:1883"     # Default MQTT broker
export MQTT_USERNAME="your-mqtt-username"            # MQTT auth username
export MQTT_PASSWORD="your-mqtt-password"            # MQTT auth password
```

**Optional for Home Assistant:**
```bash
export HA_URL="http://homeassistant.local:8123"      # Home Assistant URL
export HA_ACCESS_TOKEN="your-long-lived-token"       # HA access token
```

### Running the Server

```bash
# With environment variables set
domotz-mcp

# Or with npx
npx domotz-mcp@latest
```

## 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)

**Example:**
```json
{
  "page_size": "10",
  "page_number": "0"
}
```

### 2. get_agent
Get details of a specific Domotz agent.

**Parameters:**
- `agent_id` (number): The ID of the agent to retrieve

**Example:**
```json
{
  "agent_id": 12345
}
```

### 3. get_domotz_data
Fetch data from any Domotz API endpoint.

**Parameters:**
- `endpoint` (string): The API endpoint path (e.g., 'agents', 'devices')
- `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

**Example:**
```json
{
  "endpoint": "agents/12345/devices",
  "method": "GET"
}
```

### 4. bind_webhook
Bind a webhook to a Domotz agent for receiving events.

**Parameters:**
- `agent_id` (number): The ID of the agent
- `webhook_url` (string): The webhook URL to receive events
- `events` (array, optional): Array of event types to subscribe to

**Example:**
```json
{
  "agent_id": 12345,
  "webhook_url": "https://your-server.com/webhook",
  "events": ["device_status_change", "alert"]
}
```

### 5. bms_connect
Connect to BMS controller and retrieve data points.

**Parameters:**
- `ip` (string): IP address of the BMS controller
- `port` (string): Port number (default: 80)
- `protocol` (string): Connection protocol
- `username` (string, optional): Username for authentication
- `password` (string, optional): Password for authentication

**Example:**
```json
{
  "ip": "192.168.1.100",
  "port": "80",
  "protocol": "http"
}
```

### 6. bms_monitor
Start continuous monitoring of BMS controller data points.

**Parameters:**
- `ip` (string): IP address of the BMS controller
- `port` (string): Port number (default: 80)
- `protocol` (string): Connection protocol
- `interval` (string): Monitoring interval in seconds
- `username` (string, optional): Username for authentication
- `password` (string, optional): Password for authentication
- `data_points` (array, optional): Specific data points to monitor

**Example:**
```json
{
  "ip": "192.168.1.100",
  "port": "80",
  "protocol": "http",
  "interval": "60",
  "data_points": ["temperature", "humidity", "pressure"]
}
```

## Integration with MCP Clients

### Claude Desktop

Add to your Claude configuration file:

**Complete Configuration:**
```json
{
  "mcpServers": {
    "domotz": {
      "command": "npx",
      "args": ["domotz-mcp@latest"],
      "env": {
        "DOMOTZ_API_KEY": "your-api-key",
        "DOMOTZ_API_ENDPOINT": "https://api-eu-west-1-cell-1.domotz.com/public-api/v1/",
        "MQTT_BROKER_URL": "mqtt://your-broker:1883",
        "MQTT_USERNAME": "mqtt-username",
        "MQTT_PASSWORD": "mqtt-password",
        "HA_URL": "http://homeassistant.local:8123",
        "HA_ACCESS_TOKEN": "your-ha-token"
      }
    }
  }
}
```

**Minimal Configuration (Domotz only):**
```json
{
  "mcpServers": {
    "domotz": {
      "command": "npx",
      "args": ["domotz-mcp@latest"],
      "env": {
        "DOMOTZ_API_KEY": "your-api-key",
        "DOMOTZ_API_ENDPOINT": "https://api-eu-west-1-cell-1.domotz.com/public-api/v1/"
      }
    }
  }
}
```

### VS Code with Roo Cline

Add to your MCP settings:

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

## Troubleshooting

1. **401 Invalid API Key**: Make sure you have set a valid DOMOTZ_API_KEY
2. **Connection errors**: Check your DOMOTZ_API_ENDPOINT is correct
3. **Tool not found**: Ensure you're using the correct tool name and parameters

## Support

For issues or questions, please visit the [GitHub repository](https://github.com/your-repo/domotz-mcp).