homeassistant-ai/ha-mcp

YouTube version →

✨ Features

🔍 Discover, Search and Query

• Fuzzy Entity Search: Comprehensive search with typo tolerance
• AI-Optimized System Overview: Complete system analysis showing entity counts, areas, and device status
• Intelligent Entity Matching: Advanced search across all Home Assistant entities with partial name matching
• Template Evaluation: Evaluate Home Assistant templates for dynamic data processing and calculations
• Logbook Data Access: Query logbook entries with date filtering and entity-specific searches

🏠 Control

• Universal Service Control: Execute any Home Assistant service with full parameter support
• Real-time State Access: Get detailed entity states with attributes, timestamps, and context information

🔧 Manage

• Automation and Scripts: Create, modify, delete, enable/disable, and trigger Home Assistant automations
• Helper Entity Management: Create, modify, and delete input_boolean, input_number, input_select, input_text, input_datetime, and input_button entities
• Backup and Restore: Create fast local backups (excludes database) and restore with safety mechanisms (configurable)

🚀 Quick Start

Prerequisites

• Long-lived access token from Home Assistant user profile - Security tab

Installation

1. Install uv

   uv is a Python package manager (Python installation not required). Follow instructions at https://docs.astral.sh/uv/getting-started/installation/

2. Clone the repository

   git clone https://github.com/homeassistant-ai/ha-mcp
   cd ha-mcp
   

Client Configuration

mcp.json format (Claude Desktop, VSCode, etc.)

Linux/WSL/macOS:

{
  "mcpServers": {

    "Home Assistant": {
      "command": "path/to/ha-mcp/run_mcp_server.sh",
      "args": [],
      "env": {
        "HOMEASSISTANT_URL": "http://localhost:8123",
        "HOMEASSISTANT_TOKEN": "your_long_lived_access_token_from_home_assistant_profile"
      }
    }

  }
}

Windows:

{
  "mcpServers": {

    "Home Assistant": {
      "command": "C:\\path\\to\\ha-mcp\\run_mcp_server.bat",
      "args": [],
      "env": {
        "HOMEASSISTANT_URL": "http://localhost:8123",
        "HOMEASSISTANT_TOKEN": "your_long_lived_access_token_from_home_assistant_profile"
      }
    }

  }
}

Optional Configuration

BACKUP_HINT - Controls backup tool recommendation behavior:

• strong: Suggests backup before the FIRST modification of day/session (for very cautious users)
• normal: Suggests backup only before operations that CANNOT be undone (default, recommended)
• weak: Rarely suggests backups (only if explicitly requested)
• auto: Currently same as normal, will auto-detect in future

Add to env section: "BACKUP_HINT": "normal"

Claude Code

cd ha-mcp
uv sync
claude mcp add ha-mcp -- uv --directory /path/to/ha-mcp --env HOMEASSISTANT_URL=http://localhost:8123 --env HOMEASSISTANT_TOKEN=your_token run fastmcp run
claude mcp add-json ha-mcp '{"type":"stdio","command":"uv","args":["--directory","/path/to/ha-mcp","run","fastmcp","run"],"env":{"HOMEASSISTANT_URL":"http://localhost:8123","HOMEASSISTANT_TOKEN":"your_token"}}'

Remote mode (for compatibility with remote mcp)

1. Configure environment

   cp .env.example .env
   # Edit .env with your Home Assistant details:
   HOMEASSISTANT_URL=http://localhost:8123
   HOMEASSISTANT_TOKEN=your_token
   

2. Start the server

uv run fastmcp run --transport streamable-http --port 8086

Server will be available at http://127.0.0.1:8086/mcp

Online clients (Claude.ai, ChatGPT.com, ...)

WARNING! This is not the most secure way of connecting those providers. Use this setup at your own risk. Anybody figuring out how to do it properly is welcome to contribute to this project. Check out https://gofastmcp.com/servers/auth/authentication for more information.

This setup consists of an HTTPS tunnel with cloudflared tunnel.

1. Install cloudflared See https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/

2. Configure environment

   cp .env.example .env
   # Edit .env with your Home Assistant details:
   HOMEASSISTANT_URL=http://localhost:8123
   HOMEASSISTANT_TOKEN=your_token
   

3. Run the MCP server

uv run fastmcp run --transport streamable-http --port 8086 --path __my_secret_key_that_should_not_be_shared_with_anyone__

Replace the path parameter with a secret value!

4. Start the tunnel

cloudflared tunnel --url http://localhost:8086

You will find the base url in your output. It will look like this: https://abc-def-ghi.trycloudflare.com

Append your secret path and use the url in the online provider (Claude.ai and such)

The url should look like: https://abc-def-ghi.trycloudflare.com/__my_secret_key_that_should_not_be_shared_with_anyone__

For Claude.AI: https://support.anthropic.com/en/articles/11176164-pre-built-web-connectors-using-remote-mcp For ChatGPT.com: https://help.openai.com/en/articles/11487775-connectors-in-chatgpt (untested)

🛠️ Available Tools

Search & Discovery Tools

Core Home Assistant API Tools

Device Control Tools

Convenience Tools

Helper Entity Management Tools

Script Management Tools

Automation Management Tools

Template & Data Tools

Documentation Tools

🤝 Contributing

For development setup, testing instructions, and contribution guidelines, see .

For comprehensive testing documentation, see .

🛣️ Development Roadmap

Completed ✅

• Core infrastructure and HTTP client
• FastMCP integration with OpenAPI auto-generation
• Smart search tools with fuzzy matching
• Optimized tool documentation to reduce tool call errors
• WebSocket async device control
• Convenience tools for scenes and automations
• Comprehensive test suite

For future enhancements and planned features, see the Development Roadmap in our wiki.

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• Home Assistant: Amazing smart home platform (!)
• FastMCP: Excellent MCP server framework
• Model Context Protocol: Standardized AI-application communication
• Claude Code: AI-powered coding assistant