Skip to content

Add-on Management Tool

The Add-on Management tool provides functionality to manage Home Assistant add-ons through the MCP interface.

Features

  • List available add-ons
  • Install/uninstall add-ons
  • Start/stop/restart add-ons
  • Get add-on information
  • Update add-ons
  • Configure add-ons
  • View add-on logs
  • Monitor add-on status

Usage

REST API

GET /api/addons
GET /api/addons/{addon_slug}
POST /api/addons/{addon_slug}/install
POST /api/addons/{addon_slug}/uninstall
POST /api/addons/{addon_slug}/start
POST /api/addons/{addon_slug}/stop
POST /api/addons/{addon_slug}/restart
GET /api/addons/{addon_slug}/logs
PUT /api/addons/{addon_slug}/config
GET /api/addons/{addon_slug}/stats

WebSocket

// List add-ons
{
    "type": "get_addons"
}

// Get add-on info
{
    "type": "get_addon_info",
    "addon_slug": "required_addon_slug"
}

// Install add-on
{
    "type": "install_addon",
    "addon_slug": "required_addon_slug",
    "version": "optional_version"
}

// Control add-on
{
    "type": "control_addon",
    "addon_slug": "required_addon_slug",
    "action": "start|stop|restart"
}

Examples

List All Add-ons

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

Install Add-on

const response = await fetch('http://your-ha-mcp/api/addons/mosquitto/install', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer your_access_token',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "version": "latest"
    })
});

Configure Add-on

const response = await fetch('http://your-ha-mcp/api/addons/mosquitto/config', {
    method: 'PUT',
    headers: {
        'Authorization': 'Bearer your_access_token',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "logins": [
            {
                "username": "mqtt_user",
                "password": "mqtt_password"
            }
        ],
        "customize": {
            "active": true,
            "folder": "mosquitto"
        }
    })
});

Response Format

Add-on List Response

{
    "success": true,
    "data": {
        "addons": [
            {
                "slug": "addon_slug",
                "name": "Add-on Name",
                "version": "1.0.0",
                "state": "started",
                "repository": "core",
                "installed": true,
                "update_available": false
            }
        ]
    }
}

Add-on Info Response

{
    "success": true,
    "data": {
        "addon": {
            "slug": "addon_slug",
            "name": "Add-on Name",
            "version": "1.0.0",
            "description": "Add-on description",
            "long_description": "Detailed description",
            "repository": "core",
            "installed": true,
            "state": "started",
            "webui": "http://[HOST]:[PORT:80]",
            "boot": "auto",
            "options": {
                // Add-on specific options
            },
            "schema": {
                // Add-on options schema
            },
            "ports": {
                "80/tcp": 8080
            },
            "ingress": true,
            "ingress_port": 8099
        }
    }
}

Add-on Stats Response

{
    "success": true,
    "data": {
        "stats": {
            "cpu_percent": 2.5,
            "memory_usage": 128974848,
            "memory_limit": 536870912,
            "network_rx": 1234,
            "network_tx": 5678,
            "blk_read": 12345,
            "blk_write": 67890
        }
    }
}

Error Handling

Common Error Codes

  • 404: Add-on not found
  • 401: Unauthorized
  • 400: Invalid request
  • 409: Add-on operation failed
  • 422: Invalid configuration

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:
  • ADDON_RATE_LIMIT
  • ADDON_RATE_WINDOW

Best Practices

  1. Always check add-on compatibility
  2. Back up configurations before updates
  3. Monitor resource usage
  4. Use appropriate update strategies
  5. Implement proper error handling
  6. Test configurations in safe environment
  7. Handle rate limiting gracefully
  8. Keep add-ons updated

Add-on Security

  • Use secure passwords
  • Regularly update add-ons
  • Monitor add-on logs
  • Restrict network access
  • Use SSL/TLS when available
  • Follow principle of least privilege

See Also