homeassistant-mcp/docs/tools/automation/automation-config.md

Automation Configuration Tool

The Automation Configuration tool provides functionality to create, update, and manage Home Assistant automation configurations.

Features

• Create new automations
• Update existing automations
• Delete automations
• Duplicate automations
• Import/Export automation configurations
• Validate automation configurations

Usage

REST API

POST /api/automations
PUT /api/automations/{automation_id}
DELETE /api/automations/{automation_id}
POST /api/automations/{automation_id}/duplicate
POST /api/automations/validate

WebSocket

// Create automation
{
    "type": "create_automation",
    "automation": {
        // Automation configuration
    }
}

// Update automation
{
    "type": "update_automation",
    "automation_id": "required_automation_id",
    "automation": {
        // Updated configuration
    }
}

// Delete automation
{
    "type": "delete_automation",
    "automation_id": "required_automation_id"
}

Automation Configuration

Basic Structure

{
    "id": "morning_routine",
    "alias": "Morning Routine",
    "description": "Turn on lights and adjust temperature in the morning",
    "trigger": [
        {
            "platform": "time",
            "at": "07:00:00"
        }
    ],
    "condition": [
        {
            "condition": "time",
            "weekday": ["mon", "tue", "wed", "thu", "fri"]
        }
    ],
    "action": [
        {
            "service": "light.turn_on",
            "target": {
                "entity_id": "light.bedroom"
            },
            "data": {
                "brightness": 255,
                "transition": 300
            }
        }
    ],
    "mode": "single"
}

Trigger Types

// Time-based trigger
{
    "platform": "time",
    "at": "07:00:00"
}

// State-based trigger
{
    "platform": "state",
    "entity_id": "binary_sensor.motion",
    "to": "on"
}

// Event-based trigger
{
    "platform": "event",
    "event_type": "custom_event"
}

// Numeric state trigger
{
    "platform": "numeric_state",
    "entity_id": "sensor.temperature",
    "above": 25
}

Condition Types

// Time condition
{
    "condition": "time",
    "after": "07:00:00",
    "before": "22:00:00"
}

// State condition
{
    "condition": "state",
    "entity_id": "device_tracker.phone",
    "state": "home"
}

// Numeric state condition
{
    "condition": "numeric_state",
    "entity_id": "sensor.temperature",
    "below": 25
}

Action Types

// Service call action
{
    "service": "light.turn_on",
    "target": {
        "entity_id": "light.bedroom"
    }
}

// Delay action
{
    "delay": "00:00:30"
}

// Scene activation
{
    "scene": "scene.evening_mode"
}

// Conditional action
{
    "choose": [
        {
            "conditions": [
                {
                    "condition": "state",
                    "entity_id": "sun.sun",
                    "state": "below_horizon"
                }
            ],
            "sequence": [
                {
                    "service": "light.turn_on",
                    "target": {
                        "entity_id": "light.living_room"
                    }
                }
            ]
        }
    ]
}

Examples

Create New Automation

const response = await fetch('http://your-ha-mcp/api/automations', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer your_access_token',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "alias": "Morning Routine",
        "description": "Turn on lights in the morning",
        "trigger": [
            {
                "platform": "time",
                "at": "07:00:00"
            }
        ],
        "action": [
            {
                "service": "light.turn_on",
                "target": {
                    "entity_id": "light.bedroom"
                }
            }
        ]
    })
});

Update Existing Automation

const response = await fetch('http://your-ha-mcp/api/automations/morning_routine', {
    method: 'PUT',
    headers: {
        'Authorization': 'Bearer your_access_token',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "alias": "Morning Routine",
        "trigger": [
            {
                "platform": "time",
                "at": "07:30:00"  // Updated time
            }
        ],
        "action": [
            {
                "service": "light.turn_on",
                "target": {
                    "entity_id": "light.bedroom"
                }
            }
        ]
    })
});

Response Format

Success Response

{
    "success": true,
    "data": {
        "automation": {
            "id": "created_automation_id",
            // Full automation configuration
        }
    }
}

Validation Response

{
    "success": true,
    "data": {
        "valid": true,
        "warnings": [
            "No conditions specified"
        ]
    }
}

Error Handling

Common Error Codes

• 404: Automation not found
• 401: Unauthorized
• 400: Invalid configuration
• 409: Automation creation/update failed

Error Response Format

{
    "success": false,
    "message": "Error description",
    "error_code": "ERROR_CODE",
    "validation_errors": [
        {
            "path": "trigger[0].platform",
            "message": "Invalid trigger platform"
        }
    ]
}

Best Practices

1. Always validate configurations before saving
2. Use descriptive aliases and descriptions
3. Group related automations
4. Test automations in a safe environment
5. Document automation dependencies
6. Use variables for reusable values
7. Implement proper error handling
8. Consider automation modes carefully

See Also

• Automation Management
• Event Subscription
• Scene Management