Skip to content

# Device Control Tool

The Device Control tool provides functionality to control various types of devices in your Home Assistant instance.

## Supported Device Types

- Lights
- Switches
- Covers
- Climate devices
- Media players
- And more...

## Usage

### REST API

    POST /api/devices/{device_id}/control

### WebSocket

    {
        "type": "control_device",
        "device_id": "required_device_id",
        "domain": "required_domain",
        "service": "required_service",
        "data": {
            // Service-specific data
        }
    }

## Domain-Specific Commands

### Lights

    // Turn on/off
    POST /api/devices/light/{device_id}/control
    {
        "service": "turn_on",  // or "turn_off"
    }

    // Set brightness
    {
        "service": "turn_on",
        "data": {
            "brightness": 255  // 0-255
        }
    }

    // Set color
    {
        "service": "turn_on",
        "data": {
            "rgb_color": [255, 0, 0]  // Red
        }
    }

### Covers

    // Open/close
    POST /api/devices/cover/{device_id}/control
    {
        "service": "open_cover",  // or "close_cover"
    }

    // Set position
    {
        "service": "set_cover_position",
        "data": {
            "position": 50  // 0-100
        }
    }

### Climate

    // Set temperature
    POST /api/devices/climate/{device_id}/control
    {
        "service": "set_temperature",
        "data": {
            "temperature": 22.5
        }
    }

    // Set mode
    {
        "service": "set_hvac_mode",
        "data": {
            "hvac_mode": "heat"  // heat, cool, auto, off
        }
    }

## Examples

### Control Light Brightness

    const response = await fetch('http://your-ha-mcp/api/devices/light/living_room/control', {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer your_access_token',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            "service": "turn_on",
            "data": {
                "brightness": 128
            }
        })
    });

### Control Cover Position

    const response = await fetch('http://your-ha-mcp/api/devices/cover/bedroom/control', {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer your_access_token',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            "service": "set_cover_position",
            "data": {
                "position": 75
            }
        })
    });

## Response Format

### Success Response

    {
        "success": true,
        "data": {
            "state": "on",
            "attributes": {
                // Updated device attributes
            }
        }
    }

### Error Response

    {
        "success": false,
        "message": "Error description",
        "error_code": "ERROR_CODE"
    }

## Error Handling

### Common Error Codes

- `404`: Device not found
- `401`: Unauthorized
- `400`: Invalid service or parameters
- `409`: Device unavailable or offline

## Rate Limiting

- Default limit: 100 requests per 15 minutes
- Configurable through environment variables:
- `DEVICE_CONTROL_RATE_LIMIT`
- `DEVICE_CONTROL_RATE_WINDOW`

## Best Practices

1. Validate device availability before sending commands
2. Implement proper error handling
3. Use appropriate retry strategies for failed commands
4. Cache device capabilities when possible
5. Handle rate limiting gracefully

## See Also

- List Devices
- Device History
- Event Subscription

February 5, 2025
February 5, 2025
Was this page helpful?
Thanks for your feedback!
Thanks for your feedback! Please consider creating an issue to help us improve.

#### Cookie consent

We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.

- Google Analytics
- GitHub

Manage settings