homeassistant-mcp/docs/API.md

Home Assistant MCP API Documentation

Overview

The Home Assistant Model Context Protocol (MCP) Server provides a comprehensive API for managing and controlling your Home Assistant instance. This document outlines all available endpoints, their parameters, and includes practical examples.

Authentication

All API requests require authentication using a Bearer token.

Authorization: Bearer your_home_assistant_token

Rate Limiting

The API implements rate limiting with the following defaults:

• 100 requests per 15-minute window per IP
• Model-specific limits:
  • Claude: 100 requests/minute, 1000/hour
  • GPT-4: 50 requests/minute, 500/hour
  • Custom: 200 requests/minute, 2000/hour

Endpoints

1. Natural Language Processing

POST /interpret

Interprets natural language commands for Home Assistant control.

Request Body:

{
  "input": "Turn on the living room lights",
  "context": {
    "user_id": "user123",
    "session_id": "sess456",
    "timestamp": "2024-03-20T10:30:00Z",
    "location": "home",
    "previous_actions": [],
    "environment_state": {}
  },
  "model": "claude"  // Optional: defaults to "claude"
}

Response:

{
  "natural_language": "I'll turn on the living room lights",
  "structured_data": {
    "success": true,
    "action_taken": "turn_on",
    "entities_affected": ["light.living_room"],
    "state_changes": {
      "state": "on"
    }
  },
  "next_suggestions": [
    "Would you like to adjust the brightness?",
    "Should I turn on other lights?",
    "Would you like to save this as a scene?"
  ],
  "confidence": 0.95,
  "context": {
    "user_id": "user123",
    "session_id": "sess456",
    "timestamp": "2024-03-20T10:30:00Z"
  }
}

2. Device Control

POST /control

Controls Home Assistant devices and services.

Request Body:

{
  "command": "turn_on",
  "entity_id": "light.living_room",
  "brightness": 255,
  "color_temp": 4000,
  "rgb_color": [255, 0, 0]
}

Example Commands by Device Type:

1. Lights:

{
  "command": "turn_on",
  "entity_id": "light.bedroom",
  "brightness": 128,
  "color_temp": 3500
}

2. Climate:

{
  "command": "set_temperature",
  "entity_id": "climate.living_room",
  "temperature": 72,
  "hvac_mode": "heat"
}

3. Covers:

{
  "command": "set_position",
  "entity_id": "cover.garage",
  "position": 50
}

3. History

GET /history

Retrieves state history for entities.

Query Parameters:

• entity_id (required): Entity ID to get history for
• start_time (optional): Start time in ISO format
• end_time (optional): End time in ISO format
• minimal_response (optional): Boolean to reduce response size
• significant_changes_only (optional): Boolean to filter minor changes

Example Request:

GET /history?entity_id=light.living_room&start_time=2024-03-19T00:00:00Z&minimal_response=true

4. Scenes

GET /scenes

Lists all available scenes.

Response:

{
  "success": true,
  "scenes": [
    {
      "entity_id": "scene.movie_time",
      "name": "Movie Time",
      "description": "Dim lights and lower blinds"
    }
  ]
}

POST /scenes/activate

Activates a scene.

Request Body:

{
  "scene_id": "scene.movie_time"
}

5. Automations

GET /automations

Lists all automations.

Response:

{
  "success": true,
  "automations": [
    {
      "entity_id": "automation.morning_routine",
      "name": "Morning Routine",
      "state": "on",
      "last_triggered": "2024-03-20T06:00:00Z"
    }
  ]
}

POST /automations

Creates or modifies automations.

Request Body (Create):

{
  "action": "create",
  "config": {
    "alias": "Morning Routine",
    "description": "Turn on lights at sunrise",
    "trigger": {
      "platform": "sun",
      "event": "sunrise"
    },
    "action": {
      "service": "light.turn_on",
      "target": {
        "entity_id": "light.living_room"
      }
    }
  }
}

6. Add-ons

GET /addons

Lists available add-ons.

Response:

{
  "success": true,
  "addons": [
    {
      "name": "File Editor",
      "slug": "core_configurator",
      "description": "Simple browser-based file editor",
      "version": "5.6.0",
      "installed": true,
      "available": true,
      "state": "started"
    }
  ]
}

POST /addons

Manages add-ons.

Request Body (Install):

{
  "action": "install",
  "slug": "core_configurator",
  "version": "5.6.0"
}

7. Package Management (HACS)

GET /packages

Lists available HACS packages.

Query Parameters:

• category: One of ["integration", "plugin", "theme", "python_script", "appdaemon", "netdaemon"]

Response:

{
  "success": true,
  "packages": [
    {
      "name": "Custom Component",
      "repository": "owner/repo",
      "category": "integration",
      "installed_version": "1.0.0",
      "available_version": "1.1.0"
    }
  ]
}

POST /packages

Manages HACS packages.

Request Body (Install):

{
  "action": "install",
  "category": "integration",
  "repository": "owner/repo",
  "version": "1.1.0"
}

Error Handling

All endpoints return errors in a consistent format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "suggestion": "Suggestion to fix the error",
    "recovery_options": [
      "Option 1",
      "Option 2"
    ]
  }
}

Common HTTP status codes:

• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 429: Too Many Requests
• 500: Internal Server Error

WebSocket Events

The server supports WebSocket connections for real-time updates.

Connection

const ws = new WebSocket('ws://your-server/api/websocket');
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

Event Subscription

// Subscribe to all events
ws.send(JSON.stringify({
  type: 'subscribe_events'
}));

// Subscribe to specific event type
ws.send(JSON.stringify({
  type: 'subscribe_events',
  event_type: 'state_changed'
}));

Security Best Practices

1. Always use HTTPS in production
2. Store tokens securely
3. Implement proper token rotation
4. Monitor and log API usage
5. Regular security audits

Rate Limiting Headers

The API includes rate limit information in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1621436800