2026-02-10 13:24:32 -05:00

5.9 KiB

Raw Blame History

MCP Bridge - Home Assistant Integration

Bridge integration between Home Assistant and MCP (Model Context Protocol) servers, enabling AI agents to control your smart home.

Features

🎯 Selective Entity Exposure: Only expose entities you explicitly mark via Voice Assistant settings
🔒 Secure Script Access: Control which scripts AI can execute using labels
📊 Rich Metadata: Provides complete entity information including area, device class, and capabilities
🔌 Zero Configuration: Works out of the box after installation
🤖 AI-Ready: Designed for MCP servers and AI agent integration

What is MCP?

MCP (Model Context Protocol) is Anthropic's protocol for connecting AI agents to external tools and data sources. This integration makes your Home Assistant instance accessible to AI agents via MCP servers.

Installation

Via HACS (Recommended)

Add Custom Repository
- Open HACS in Home Assistant
- Click the three dots (⋮) in top right
- Select "Custom repositories"
- Repository: http://your-gitea-server/username/homeassistant-mcp-bridge
- Category: Integration
- Click "Add"
Install
- HACS → Integrations
- Click "+ Explore & Download Repositories"
- Search for "MCP Bridge"
- Click "Download"
- Restart Home Assistant

Manual Installation

Copy custom_components/mcp_bridge to your Home Assistant config directory
Restart Home Assistant

See INSTALLATION_GUIDE.md for detailed instructions.

Quick Start

1. Expose Entities

Go to Settings → Voice Assistants → Expose and toggle the entities you want the AI to control.

2. Mark Scripts as Accessible

For custom scripts:

Go to Settings → Automations & Scenes → Scripts
Click your script → Settings icon (⚙️)
Add label: mcp_accessible
Save

3. Test the Services

Developer Tools → Services:

service: mcp_bridge.get_exposed_entities

service: mcp_bridge.get_exposed_scripts

Services

`mcp_bridge.get_exposed_entities`

Returns all entities exposed to voice assistants with complete metadata.

Example Response:

{
  "entities": [
    {
      "entity_id": "light.living_room",
      "state": "on",
      "friendly_name": "Living Room Light",
      "area": "Living Room",
      "domain": "light",
      "supported_features": 43,
      "attributes": {...}
    }
  ],
  "count": 1
}

`mcp_bridge.get_exposed_scripts`

Returns scripts marked with mcp_accessible label, including their parameters.

Example Response:

{
  "scripts": [
    {
      "entity_id": "script.set_fan_speed",
      "friendly_name": "Set Fan Speed",
      "description": "Control bedroom fan",
      "fields": {
        "speed": {
          "name": "Speed",
          "description": "0=off, 1=low, 2=medium, 3=high",
          "required": true,
          "selector": {"number": {"min": 0, "max": 3}}
        }
      }
    }
  ],
  "count": 1
}

`mcp_bridge.get_entity_metadata`

Get detailed metadata for a specific entity.

Parameters:

entity_id: The entity to query

Architecture

AI Agent (Claude/n8n)
    ↓
MCP Server
    ↓
mcp_bridge Services
    ↓
Home Assistant

The integration provides three services that MCP servers can call to:

Discover available entities
Discover available scripts
Query entity states and metadata

Use Cases

Voice Control: "Turn on the living room lights"
Automated Scenes: AI suggests and executes scenes based on context
Smart Responses: "What's the temperature in the bedroom?"
Custom Automations: Execute complex scripts via natural language

Configuration

No configuration required! The integration automatically loads on Home Assistant restart.

Optional: Control which entities/scripts are exposed using:

Voice Assistant exposure settings (for entities)
mcp_accessible label (for scripts)

Compatibility

Home Assistant: 2024.1.0 or newer
HACS: Any version
Python: 3.11+

Documentation

Installation Guide - Detailed setup instructions
Integration README - Technical details
Gitea Setup Guide - For hosting on your own Gitea

Development

Running Tests

pytest custom_components/mcp_bridge/test_init.py

Project Structure

homeassistant-mcp-bridge/
├── custom_components/
│   └── mcp_bridge/
│       ├── __init__.py         # Core integration logic
│       ├── manifest.json       # Integration metadata
│       ├── services.yaml       # Service definitions
│       └── README.md          # Integration docs
├── hacs.json                  # HACS configuration
├── info.md                    # HACS UI description
└── README.md                  # This file

Contributing

This is a personal project for homelab use, but suggestions and improvements are welcome!

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

Roadmap

Basic entity exposure
Script discovery with labels
Complete metadata support
Real-time state updates via WebSocket
Custom entity tags beyond voice assistant exposure
Integration config flow (UI-based setup)
Service call history/logging

License

MIT License - Use freely in your homelab!

Support

Issues: Gitea Issues
Logs: Settings → System → Logs (filter by "mcp_bridge")

Acknowledgments

Built for use with Anthropic's MCP
Designed to work with n8n workflows

Made with ❤️ for home automation enthusiasts

5.9 KiB Raw Blame History