MCP (Model Context Protocol) server add-on for HomeAssistant that enables Claude Desktop to interact with your HomeAssistant instance through its native Connections capability.
- ๐ Secure OAuth2 Authentication - Uses HomeAssistant's native authentication system
- ๐ Locally Hosted - Runs directly on your HomeAssistant device
- ๐ Zero Configuration - Simple installation with minimal setup required
- ๐ง Comprehensive Control - Full access to HomeAssistant functionality through MCP tools
- ๐ Multi-Architecture Support - Works on all common HomeAssistant hardware
- โ๏ธ Cloud Compatible - Works with Nabu Casa/HomeAssistant Cloud
- ๐ก๏ธ AppArmor Protected - Enhanced security with AppArmor profile
- Open your HomeAssistant instance
- Navigate to Settings โ Add-ons โ Add-on Store
- Click the three dots menu (โฎ) โ Repositories
- Add this repository URL:
https://github.com/mtebusi/ha-mcp-v2
- Click Add
- Find "HomeAssistant MCP Server" in the add-on store and click Install
Click the button above to automatically add this repository to your HomeAssistant instance.
The add-on requires minimal configuration:
log_level: info # Options: debug, info, warning, error
ssl: true # Enable SSL/TLS
certfile: fullchain.pem # SSL certificate file (optional)
keyfile: privkey.pem # SSL key file (optional)
- Start the HomeAssistant MCP Server add-on
- Open Claude Desktop
- Go to Settings โ Connections โ Add Custom Connection
- Enter your HomeAssistant URL with
/sse
appended:- Local:
https://homeassistant.local:8089/sse
- Cloud:
https://YOUR-NABU-CASA-URL/sse
- Local:
- Complete the OAuth2 authentication flow
- The MCP tools will be automatically loaded
The add-on provides 7 powerful core tools with branched operations:
Universal control for entities, devices, and services
- Get/set entity states
- Call services
- Control devices
- Manage areas
- Fire events
Configuration and YAML management
- Read/write YAML files
- Validate configuration
- Reload components
- View logs
Automation, script, and scene management
- Create/edit automations
- Manage scripts
- Control scenes
- Trigger automations
Integration and add-on management
- Install/remove integrations
- Manage add-ons
- Configure components
Dashboard and UI management
- Create/edit dashboards
- Manage cards
- Control themes
- Configure panels
System operations and diagnostics
- Restart HomeAssistant
- Create/restore backups
- View diagnostics
- Database maintenance
Template and helper management
- Render templates
- Create input helpers
- Manage counters/timers
- Python 3.12+
- Docker (for testing)
- HomeAssistant instance (for testing)
# Clone the repository
git clone https://github.com/mtebusi/ha-mcp-v2.git
cd ha-mcp-v2
# Install dependencies
pip install -r src/requirements.txt
# Run locally (requires HomeAssistant instance)
python -m src.server --debug --ha-url http://localhost:8123 --ha-token YOUR_TOKEN
# Run tests
./scripts/test.sh
# Build for local architecture
./scripts/build.sh --arch amd64
# Build all architectures
./scripts/build.sh --all
# Start test environment
docker-compose -f tests/docker-compose.yml up -d
# Run tests
pytest tests/ -v
# Stop test environment
docker-compose -f tests/docker-compose.yml down
The add-on uses a Server-Sent Events (SSE) based MCP server that:
- Runs as a HomeAssistant add-on with supervisor integration
- Exposes an SSE endpoint at
/sse
for Claude Desktop connections - Handles OAuth2 authentication flow with HomeAssistant
- Provides MCP tools that interact with HomeAssistant's REST and WebSocket APIs
- Maintains secure, persistent connections with automatic reconnection
- AppArmor Profile: Restricts file system access and capabilities
- OAuth2 Authentication: Uses HomeAssistant's native auth system
- TLS/SSL Support: Encrypted connections when configured
- Token Management: Secure token storage and refresh
- Rate Limiting: Prevents API abuse
- Input Validation: All inputs are validated and sanitized
If Claude Desktop cannot connect:
- Verify the add-on is running: Check add-on logs
- Check the URL format: Must end with
/sse
- Ensure SSL certificates are valid if using HTTPS
- Verify firewall allows port 8089
If authentication fails:
- Check HomeAssistant user permissions
- Verify OAuth2 redirect URL is accessible
- Clear browser cookies and retry
- Check add-on logs for auth errors
If tools fail to execute:
- Verify HomeAssistant API is accessible
- Check user has required permissions
- Review add-on logs for errors
- Ensure HomeAssistant version compatibility
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: Wiki
This project is licensed under the MIT License - see the LICENSE file for details.
- HomeAssistant community for the amazing platform
- Anthropic for Claude and the MCP protocol
- Contributors and testers