Skip to content

# Scene Management Tool

The Scene Management tool provides functionality to manage and control scenes in your Home Assistant instance.

## Features

- List available scenes
- Activate scenes
- Create new scenes
- Update existing scenes
- Delete scenes
- Get scene state information

## Usage

### REST API

    GET /api/scenes
    GET /api/scenes/{scene_id}
    POST /api/scenes/{scene_id}/activate
    POST /api/scenes
    PUT /api/scenes/{scene_id}
    DELETE /api/scenes/{scene_id}

### WebSocket

    // List scenes
    {
        "type": "get_scenes"
    }

    // Activate scene
    {
        "type": "activate_scene",
        "scene_id": "required_scene_id"
    }

    // Create/Update scene
    {
        "type": "create_scene",
        "scene": {
            "name": "required_scene_name",
            "entities": {
                // Entity states
            }
        }
    }

## Scene Configuration

### Scene Definition

    {
        "name": "Movie Night",
        "entities": {
            "light.living_room": {
                "state": "on",
                "brightness": 50,
                "color_temp": 2700
            },
            "cover.living_room": {
                "state": "closed"
            },
            "media_player.tv": {
                "state": "on",
                "source": "HDMI 1"
            }
        }
    }

## Examples

### List All Scenes

    const response = await fetch('http://your-ha-mcp/api/scenes', {
        headers: {
            'Authorization': 'Bearer your_access_token'
        }
    });
    const scenes = await response.json();

### Activate a Scene

    const response = await fetch('http://your-ha-mcp/api/scenes/movie_night/activate', {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer your_access_token'
        }
    });

### Create a New Scene

    const response = await fetch('http://your-ha-mcp/api/scenes', {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer your_access_token',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            "name": "Movie Night",
            "entities": {
                "light.living_room": {
                    "state": "on",
                    "brightness": 50
                },
                "cover.living_room": {
                    "state": "closed"
                }
            }
        })
    });

## Response Format

### Scene List Response

    {
        "success": true,
        "data": {
            "scenes": [
                {
                    "id": "scene_id",
                    "name": "Scene Name",
                    "entities": {
                        // Entity configurations
                    }
                }
            ]
        }
    }

### Scene Activation Response

    {
        "success": true,
        "data": {
            "scene_id": "activated_scene_id",
            "status": "activated",
            "timestamp": "2024-02-05T12:00:00Z"
        }
    }

## Error Handling

### Common Error Codes

- `404`: Scene not found
- `401`: Unauthorized
- `400`: Invalid scene configuration
- `409`: Scene activation failed

### Error Response Format

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

## Rate Limiting

- Default limit: 50 requests per 15 minutes
- Configurable through environment variables:
- `SCENE_RATE_LIMIT`
- `SCENE_RATE_WINDOW`

## Best Practices

1. Validate entity availability before creating scenes
2. Use meaningful scene names
3. Group related entities in scenes
4. Implement proper error handling
5. Cache scene configurations when possible
6. Handle rate limiting gracefully

## Scene Transitions

Scenes can include transition settings for smooth state changes:

    {
        "name": "Sunset Mode",
        "entities": {
            "light.living_room": {
                "state": "on",
                "brightness": 128,
                "transition": 5  // 5 seconds
            }
        }
    }

## See Also

- Device Control
- Device History
- Automation Management

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