Skip to content

mtebusi/ha-mcp-v2

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 

History

5 Commits
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

HomeAssistant MCP Server Add-on

GitHub Release GitHub Activity License Build Status Test Coverage

Supports amd64 Architecture Supports aarch64 Architecture Supports armhf Architecture Supports armv7 Architecture Supports i386 Architecture

Add to my Home Assistant

MCP (Model Context Protocol) server add-on for HomeAssistant that enables Claude Desktop to interact with your HomeAssistant instance through its native Connections capability.

Features

  • ๐Ÿ” 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

Installation

Method 1: Add Repository to HomeAssistant

  1. Open your HomeAssistant instance
  2. Navigate to Settings โ†’ Add-ons โ†’ Add-on Store
  3. Click the three dots menu (โ‹ฎ) โ†’ Repositories
  4. Add this repository URL: https://github.com/mtebusi/ha-mcp-v2
  5. Click Add
  6. Find "HomeAssistant MCP Server" in the add-on store and click Install

Method 2: One-Click Install

Add to my Home Assistant

Click the button above to automatically add this repository to your HomeAssistant instance.

Configuration

HomeAssistant Add-on Configuration

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)

Claude Desktop Setup

  1. Start the HomeAssistant MCP Server add-on
  2. Open Claude Desktop
  3. Go to Settings โ†’ Connections โ†’ Add Custom Connection
  4. Enter your HomeAssistant URL with /sse appended:
    • Local: https://homeassistant.local:8089/sse
    • Cloud: https://YOUR-NABU-CASA-URL/sse
  5. Complete the OAuth2 authentication flow
  6. The MCP tools will be automatically loaded

Available MCP Tools

The add-on provides 7 powerful core tools with branched operations:

๐ŸŽฎ ha_control

Universal control for entities, devices, and services

  • Get/set entity states
  • Call services
  • Control devices
  • Manage areas
  • Fire events

โš™๏ธ ha_config

Configuration and YAML management

  • Read/write YAML files
  • Validate configuration
  • Reload components
  • View logs

๐Ÿค– ha_automation

Automation, script, and scene management

  • Create/edit automations
  • Manage scripts
  • Control scenes
  • Trigger automations

๐Ÿ”Œ ha_integration

Integration and add-on management

  • Install/remove integrations
  • Manage add-ons
  • Configure components

๐Ÿ“Š ha_dashboard

Dashboard and UI management

  • Create/edit dashboards
  • Manage cards
  • Control themes
  • Configure panels

๐Ÿ–ฅ๏ธ ha_system

System operations and diagnostics

  • Restart HomeAssistant
  • Create/restore backups
  • View diagnostics
  • Database maintenance

๐Ÿ“ ha_template

Template and helper management

  • Render templates
  • Create input helpers
  • Manage counters/timers

Development

Prerequisites

  • Python 3.12+
  • Docker (for testing)
  • HomeAssistant instance (for testing)

Local Development

# 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

Building the Add-on

# Build for local architecture
./scripts/build.sh --arch amd64

# Build all architectures
./scripts/build.sh --all

Testing

# 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

Architecture

The add-on uses a Server-Sent Events (SSE) based MCP server that:

  1. Runs as a HomeAssistant add-on with supervisor integration
  2. Exposes an SSE endpoint at /sse for Claude Desktop connections
  3. Handles OAuth2 authentication flow with HomeAssistant
  4. Provides MCP tools that interact with HomeAssistant's REST and WebSocket APIs
  5. Maintains secure, persistent connections with automatic reconnection

Security

  • 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

Troubleshooting

Connection Issues

If Claude Desktop cannot connect:

  1. Verify the add-on is running: Check add-on logs
  2. Check the URL format: Must end with /sse
  3. Ensure SSL certificates are valid if using HTTPS
  4. Verify firewall allows port 8089

Authentication Issues

If authentication fails:

  1. Check HomeAssistant user permissions
  2. Verify OAuth2 redirect URL is accessible
  3. Clear browser cookies and retry
  4. Check add-on logs for auth errors

Tool Execution Issues

If tools fail to execute:

  1. Verify HomeAssistant API is accessible
  2. Check user has required permissions
  3. Review add-on logs for errors
  4. Ensure HomeAssistant version compatibility

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass
  5. Submit a pull request

Support

License

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

Acknowledgments

  • HomeAssistant community for the amazing platform
  • Anthropic for Claude and the MCP protocol
  • Contributors and testers

About

HomeAssistant MCP Server Add-on for Claude Desktop integration

Resources

License

Stars

Watchers

Forks

Packages

 
 
 

Contributors 2

  •  
  •