Home Assistant Claude AI MCP Integration

Connect Claude Desktop to your Home Assistant instance using the Model Context Protocol (MCP).

🚀 Features

• Zero-Configuration Setup - Works immediately after installation
• Natural Language Control - Control your entire smart home conversationally
• Full Home Assistant Integration - Access all exposed entities and services
• Secure by Default - OAuth2 authentication and SSL support
• Real-time Communication - Server-Sent Events (SSE) transport
• Multi-Architecture Support - ARM, x86, and more

📦 Installation

Quick Start

1. Add Repository to Home Assistant

   Settings → Add-ons → Add-on Store → ⋮ → Repositories
   Add: https://github.com/mtebusi/ha-mcp
   

2. Install the Add-on

   • Find "Claude AI MCP Bridge for Smart Home Control"
   • Click Install
   • Click Start

3. Connect Claude Desktop

   • Open Claude Desktop
   • Settings → Custom Connectors → Add Remote MCP Server
   • Enter: http://homeassistant.local:8123
   • The add-on will be discovered automatically!

🎯 Usage

Once connected, you can control your Home Assistant with natural language:

• "Turn on the living room lights"
• "What's the temperature in the bedroom?"
• "Lock all doors"
• "Set the house to night mode"
• "Show me energy usage for today"

📚 Documentation

• Add-on Documentation
• Changelog
• Configuration Guide

🏗️ Repository Structure

ha-mcp/
├── claude-ai-mcp/        # Main Home Assistant add-on
│   ├── mcp-server/       # TypeScript MCP server implementation
│   ├── rootfs/           # Add-on filesystem overlay
│   ├── config.yaml       # Add-on configuration
│   └── Dockerfile        # Container build instructions
├── .github/              # GitHub Actions workflows
└── repository.yaml       # Home Assistant repository metadata

🛠️ Development

Prerequisites

• Node.js 20+
• TypeScript 5+
• Docker
• Home Assistant development environment

Building Locally

# Clone the repository
git clone https://github.com/mtebusi/ha-mcp.git
cd ha-mcp

# Install dependencies
cd claude-ai-mcp/mcp-server
npm install

# Build TypeScript
npm run build

# Build Docker image
docker build -t claude-ai-mcp claude-ai-mcp/

Testing

# Run TypeScript tests
npm test

# Type checking
npm run type-check

# Linting
npm run lint

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

• Home Assistant for the amazing smart home platform
• Anthropic for Claude and the Model Context Protocol
• The Home Assistant community for continuous support and feedback

📧 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Community: Home Assistant Community

🔗 Links

• Model Context Protocol Documentation
• Home Assistant Add-on Development
• Claude Desktop

Made with ❤️ for the Home Assistant Community