Home Assistant MCP Server

What does “Home Assistant” MCP Server do?

Home Assistant MCP Server (hass-mcp) is a Model Context Protocol (MCP) server that bridges AI assistants—such as Claude and other LLMs—with your Home Assistant ecosystem. By exposing Home Assistant’s data and functionalities via the MCP standard, it empowers AI agents to interact with, query, and control smart home devices and automations. Typical tasks enabled by hass-mcp include querying device and sensor states, toggling lights or switches, summarizing household status, troubleshooting automations, searching for specific entities, and facilitating guided conversations for common smart home activities. This integration enhances developer and user workflows by making smart home management accessible through conversational AI, automations, and LLM-powered agents.

List of Prompts

• No documented prompt templates were found in the repository.

List of Resources

• No explicit MCP resources were listed in the repository.

List of Tools

• Query the state of devices and sensors: Allows LLMs to retrieve the current status of Home Assistant entities.
• Control lights, switches, and other entities: Enables direct control (on/off, brightness, etc.) of supported smart home components.
• Get summaries of your smart home: Provides high-level overviews or aggregated information about the home’s current state.
• Troubleshoot automations and entities: Offers diagnostic information or steps for resolving issues with automations or device entities.
• Search for specific entities: Lets users or agents locate devices or sensors by name or type within Home Assistant.
• Create guided conversations for common tasks: Supports structured interactions to walk users through frequent smart home operations.

Use Cases of this MCP Server

• Device State Querying: Developers and users can programmatically or conversationally request current states (e.g., “Is the kitchen window open?”), supporting monitoring and automation logic.
• Smart Home Control: Enables voice assistants or chatbots to turn lights on/off, adjust thermostats, or control appliances, enhancing accessibility and automation.
• Home Summary Reports: LLMs can generate daily or on-demand summaries (e.g., “What’s the status of my home this evening?”) for user convenience or integration into dashboards.
• Troubleshooting Automations: Developers can leverage the MCP server to identify misconfigurations or failures in automations, streamlining debugging.
• Entity Search & Guided Task Flows: Quickly locating devices or walking users through complex multi-step routines (e.g., “Set up a morning routine”) simplifies smart home management.

How to set it up

Windsurf

1. Ensure Python and Docker are installed on your system.
2. Clone the hass-mcp repository and configure your Home Assistant connection in a .env file (see .env.example).
3. In Windsurf, open your settings’ MCP Servers section.
4. Add the hass-mcp server using a JSON configuration like:

   {
     "mcpServers": {
       "hass-mcp": {
         "command": "docker",
         "args": ["run", "--env-file=.env", "-p", "8080:8080", "voska/hass-mcp:latest"]
       }
     }
   }
   

5. Save settings and restart Windsurf. Verify the server appears in the MCP list.

Claude

1. Deploy the hass-mcp server locally or on a server accessible to Claude.
2. Secure your Home Assistant API key using environment variables.
3. In Claude’s configuration, add the MCP server entry:

   {
     "mcpServers": {
       "hass-mcp": {
         "command": "python",
         "args": ["-m", "app.main"]
       }
     }
   }
   

4. Restart Claude and check for MCP server availability.
5. Use environment variables to secure sensitive data (see below).

Cursor

1. Deploy hass-mcp and ensure network access between Cursor and the MCP server.
2. Configure Cursor to use the MCP server:

   {
     "mcpServers": {
       "hass-mcp": {
         "command": "python",
         "args": ["-m", "app.main"]
       }
     }
   }
   

3. Save configuration and restart Cursor.
4. Set environment variables for API keys as needed.

Cline

1. Install dependencies and run the hass-mcp server (see repository for details).
2. In Cline, open your MCP configuration file.
3. Add the hass-mcp server:

   {
     "mcpServers": {
       "hass-mcp": {
         "command": "python",
         "args": ["-m", "app.main"]
       }
     }
   }
   

4. Restart Cline to enable the new MCP server.

Securing API Keys (All Platforms):

Use environment variables in your configuration to protect sensitive information:

{
  "mcpServers": {
    "hass-mcp": {
      "env": {
        "HASS_TOKEN": "${HASS_TOKEN}"
      },
      "inputs": {
        "hass_url": "http://your-homeassistant.local:8123"
      }
    }
  }
}

How to use this MCP inside flows

Using MCP in FlowHunt

To integrate MCP servers into your FlowHunt workflow, start by adding the MCP component to your flow and connecting it to your AI agent:

Click on the MCP component to open the configuration panel. In the system MCP configuration section, insert your MCP server details using this JSON format:

{
  "hass-mcp": {
    "transport": "streamable_http",
    "url": "https://yourmcpserver.example/pathtothemcp/url"
  }
}

Once configured, the AI agent is now able to use this MCP as a tool with access to all its functions and capabilities. Remember to change “hass-mcp” to whatever the actual name of your MCP server is and replace the URL with your own MCP server URL.

Overview

Based on the available documentation and repository content, hass-mcp provides a solid foundation for Home Assistant integration via MCP, with clear tool support and sensible setup/security practices. However, there is a lack of explicit prompt templates, resource definitions, or advanced sampling/roots features in the public documentation. I would rate this MCP server a 6/10: functional and developer-friendly, but lacking in extensibility documentation and advanced MCP features.

MCP Score