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