Home Assistant MCP Server

Model Context Protocol (MCP) server for Home Assistant integration. This Actor provides tools and resources to interact with Home Assistant entities, services, and states via the MCP protocol.

What is Home Assistant? Home Assistant is an open-source home automation platform that acts as a central hub for controlling smart devices from different manufacturers. It supports integrations with hundreds of devices and platforms including lights, switches, sensors, climate control, media players, and more.

✨ Control any smart device - If your devices are integrated with Home Assistant, you can control them all through this MCP server!

Features

• 🔌 MCP Protocol Support - Full Model Context Protocol implementation
• 🏠 Home Assistant Integration - Direct connection to Home Assistant REST API
• 🛠️ Tools Available:
  • get_states - Get all states from Home Assistant
  • get_state - Get the state of a specific entity
  • call_service - Call a Home Assistant service
  • get_entities - Get all available entities
  • get_services - Get all available services
• 📚 Resources Available:
  • home-assistant://entities - List of all Home Assistant entities
  • home-assistant://services - List of all available services
• 💰 Pay Per Event - Flexible pricing based on tool and resource usage
• 🔄 Standby Mode - Runs as a long-running server for fast response times

Prerequisites

1. Home Assistant Installation - You need a running Home Assistant instance

   • Home Assistant is a free, open-source home automation platform
   • It can be installed on Raspberry Pi, Docker, or as a VM
   • Installation guide: https://www.home-assistant.io/installation/

2. Long-Lived Access Token - Create one at: Profile → Long-Lived Access Tokens in Home Assistant

3. (Optional) Smart Device Integration - To control your smart devices:

   • Set up your devices in Home Assistant using the appropriate integrations
   • Check the Home Assistant integrations page for available integrations
   • Common integrations include: lights, switches, sensors, climate control, media players, and more
   • Once integrated, devices appear as entities in Home Assistant
   • You can then control them through this MCP server using the call_service tool

Authentication

This Actor runs in standby mode and behaves like an API. No input is required at startup. Instead, you must include your Home Assistant credentials in each request body:

• homeAssistantUrl (required in request body): The URL of your Home Assistant instance
  • Example: https://homeassistant.local:8123
  • Example: http://192.168.1.100:8123
• homeAssistantApiKey (required in request body): Long-lived access token from Home Assistant
  • Create at: Profile → Long-Lived Access Tokens in Home Assistant

Usage

Running in Standby Mode

This Actor is designed to run in standby mode on the Apify platform. When deployed, it will:

1. Start an HTTP server listening on the configured port
2. Accept MCP requests at the /mcp endpoint
3. Process requests and return responses

Connecting with MCP Client

Once deployed, connect to your Actor using the standby URL:

https://me--home-assistant-mcp-server.apify.actor/mcp

Important: You must pass your Apify API token in the Authorization header:

Authorization: Bearer <YOUR_APIFY_API_TOKEN>

Example MCP Requests

Important: All requests must include homeAssistantUrl and homeAssistantApiKey in the request body.

List Tools

{
  "method": "tools/list",
  "params": {},
  "homeAssistantUrl": "https://homeassistant.local:8123",
  "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN"
}

Call a Tool

{
  "method": "tools/call",
  "params": {
    "name": "get_state",
    "arguments": {
      "entityId": "light.living_room"
    }
  },
  "homeAssistantUrl": "https://homeassistant.local:8123",
  "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN"
}

List Resources

{
  "method": "resources/list",
  "params": {},
  "homeAssistantUrl": "https://homeassistant.local:8123",
  "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN"
}

Read a Resource

{
  "method": "resources/read",
  "params": {
    "uri": "home-assistant://entities"
  },
  "homeAssistantUrl": "https://homeassistant.local:8123",
  "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN"
}

Available Tools

get_states

Get all states from Home Assistant.

No parameters required

get_state

Get the state of a specific entity.

Parameters:

• entityId (required): Entity ID (e.g., light.living_room, switch.coffee_maker, sensor.temperature)

Example:

{
  "method": "tools/call",
  "params": {
    "name": "get_state",
    "arguments": {
      "entityId": "light.living_room"
    }
  },
  "homeAssistantUrl": "https://homeassistant.local:8123",
  "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN"
}

call_service

Call a Home Assistant service.

Parameters:

• domain (required): Service domain (e.g., light, switch, climate, media_player)
• service (required): Service name (e.g., turn_on, turn_off, set_temperature)
• entityId (required): Entity ID (e.g., light.living_room, switch.coffee_maker)
• serviceData (optional): Additional service data

Example:

{
  "method": "tools/call",
  "params": {
    "name": "call_service",
    "arguments": {
      "domain": "light",
      "service": "turn_on",
      "entityId": "light.living_room",
      "serviceData": {
        "brightness": 255
      }
    }
  },
  "homeAssistantUrl": "https://homeassistant.local:8123",
  "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN"
}

get_entities

Get all available entities from Home Assistant. Use this to find your device entity IDs.

No parameters required

Example Response:

[
  "light.living_room",
  "switch.coffee_maker",
  "sensor.temperature",
  "climate.thermostat"
]

get_services

Get all available services from Home Assistant.

No parameters required

Available Resources

home-assistant://entities

Returns a JSON list of all Home Assistant entities with their states and attributes.

home-assistant://services

Returns a JSON list of all available Home Assistant services organized by domain.

Monetization

This Actor uses Pay Per Event (PPE) monetization:

• tool-request: $0.01 per tool call (get_state, call_service, etc.)
• resource-request: $0.005 per resource access (entities list, services list)

Local Development

1. Install dependencies:

   $bun install
   

2. Run locally:

   $bun run start
   

Note: The Actor requires standby mode to run properly. For local testing, you may need to set the APIFY_META_ORIGIN=STANDBY environment variable.

Deployment

1. Push to Apify:

   $apify push
   

2. Configure Standby Mode:

   • Go to Actor Settings in Apify Console
   • Enable "Actor Standby"
   • Configure standby settings

3. Get Standby URL:

   • The standby URL will be available in the Actor settings
   • Format: https://me--home-assistant-mcp-server.apify.actor/mcp

Security

• API Key Protection: Never commit your Home Assistant API key to version control
• HTTPS Recommended: Use HTTPS for your Home Assistant URL when possible
• Authentication Required: Always use your Apify API token when connecting to the standby endpoint

Usage Examples

This MCP server works with any device that's integrated in Home Assistant. Below are examples for common device types:

Finding Your Devices

1. List all entities to find your devices:

{
  "method": "tools/call",
  "params": {
    "name": "get_entities",
    "arguments": {}
  },
  "homeAssistantUrl": "https://homeassistant.local:8123",
  "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN"
}

Look for entities by their domain prefix:

• light.* - Lights
• switch.* - Switches
• sensor.* - Sensors
• climate.* - Thermostats/climate control
• media_player.* - Media players
• And many more...

Example: Lights

{
  "method": "tools/call",
  "params": {
    "name": "call_service",
    "arguments": {
      "domain": "light",
      "service": "turn_on",
      "entityId": "light.living_room",
      "serviceData": {
        "brightness": 255,
        "color_name": "red"
      }
    }
  },
  "homeAssistantUrl": "https://homeassistant.local:8123",
  "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN"
}

Example: Switches

{
  "method": "tools/call",
  "params": {
    "name": "call_service",
    "arguments": {
      "domain": "switch",
      "service": "turn_on",
      "entityId": "switch.coffee_maker"
    }
  },
  "homeAssistantUrl": "https://homeassistant.local:8123",
  "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN"
}

Example: Climate Control

{
  "method": "tools/call",
  "params": {
    "name": "call_service",
    "arguments": {
      "domain": "climate",
      "service": "set_temperature",
      "entityId": "climate.thermostat",
      "serviceData": {
        "temperature": 72
      }
    }
  },
  "homeAssistantUrl": "https://homeassistant.local:8123",
  "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN"
}

Example: Reading Sensors

{
  "method": "tools/call",
  "params": {
    "name": "get_state",
    "arguments": {
      "entityId": "sensor.temperature"
    }
  },
  "homeAssistantUrl": "https://homeassistant.local:8123",
  "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN"
}

Note: The exact services and entities available depend on how your devices are integrated in your Home Assistant setup. Use get_services and get_entities to discover what's available in your installation.

Troubleshooting

Connection Issues

• Verify your Home Assistant URL is accessible
• Check that your API key is valid and has not expired
• Ensure Home Assistant is running and the API is enabled

Devices Not Found

• Verify your devices are integrated in Home Assistant
• Check Home Assistant → Settings → Devices & Services
• Use get_entities to list all available entities and find your device IDs
• Common entity patterns:
  • Lights: light.*
  • Switches: switch.*
  • Sensors: sensor.*
  • Climate: climate.*
  • Media players: media_player.*

MCP Protocol Errors

• Verify request format matches MCP protocol specification
• Check that required parameters are provided
• Review Actor logs for detailed error messages

Support

For issues or questions:

• Check the Actor logs in Apify Console
• Review Home Assistant API documentation: https://www.home-assistant.io/integrations/api/
• MCP Protocol documentation: https://modelcontextprotocol.io/

License

ISC