homeassistant-mcp-bridge/README.md

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

Note: This integration is hosted on Gitea (not GitHub), so it's not available via HACS. Instead, use one of the automated installation methods below.

Method 1: One-Line Install/Update (Easiest)

Run this command in your Home Assistant terminal (requires Terminal & SSH addon or SSH access):

curl -sSL http://your-gitea.local:3000/username/homeassistant-mcp-bridge/raw/branch/main/quick_install.sh | \
  GITEA_URL=http://your-gitea.local:3000 \
  REPO=username/homeassistant-mcp-bridge \
  bash

Important:

• Replace your-gitea.local:3000 with your Gitea server address
• Replace username with your Gitea username
• Replace main with your branch name if different

After installation completes, restart Home Assistant.

Method 2: Home Assistant Auto-Update Button

Add this to your configuration.yaml to create an update button/service:

shell_command:
  update_mcp_bridge: >
    curl -fsSL http://your-gitea.local:3000/username/homeassistant-mcp-bridge/raw/branch/main/quick_install.sh | 
    GITEA_URL=http://your-gitea.local:3000 
    REPO=username/homeassistant-mcp-bridge 
    bash

script:
  update_mcp_bridge:
    alias: "Update MCP Bridge Integration"
    sequence:
      - service: shell_command.update_mcp_bridge
      - delay:
          seconds: 5
      - service: persistent_notification.create
        data:
          title: "MCP Bridge Updated"
          message: "Integration updated from Gitea. Please restart Home Assistant."

Usage:

• Go to Developer Tools → Services
• Select script.update_mcp_bridge
• Click "Call Service"
• Restart Home Assistant after update

Optional Dashboard Button:

type: button
name: Update MCP Bridge
icon: mdi:download
tap_action:
  action: call-service
  service: script.update_mcp_bridge

Method 3: Manual Installation

1. Download these files from your Gitea repository:

   • custom_components/mcp_bridge/__init__.py
   • custom_components/mcp_bridge/manifest.json
   • custom_components/mcp_bridge/services.yaml

2. Copy to /config/custom_components/mcp_bridge/

3. Restart Home Assistant

See INSTALLATION_GUIDE.md for detailed manual steps.

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:

1. Go to Settings → Automations & Scenes → Scripts
2. Click your script → Settings icon (⚙️)
3. Add label: mcp_accessible
4. 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
        }
      }
    }
  ],
  "count": 1
}

mcp_bridge.get_entity_metadata

Get detailed metadata for a specific entity.

Parameters:

• entity_id: The entity to query

Updating the Integration

Using Auto-Update Script/Button:

• Just run the install command again or call the script.update_mcp_bridge service
• Restart Home Assistant after update

Manual Update:

• Download the latest files from Gitea
• Replace files in /config/custom_components/mcp_bridge/
• Restart Home Assistant

Architecture

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

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

1. Discover available entities
2. Discover available scripts
3. 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
• Python: 3.11+
• Installation: Requires SSH/Terminal access or manual file management

Troubleshooting

Installation Script Fails

Check:

• Home Assistant can reach your Gitea server
• Terminal addon has network access
• URLs are correct (server address, username, repo name)

Test connectivity:

curl http://your-gitea.local:3000/username/homeassistant-mcp-bridge

Integration Not Loading

Check logs:

• Settings → System → Logs
• Filter by "mcp_bridge"

Common issues:

• Files not in correct location (/config/custom_components/mcp_bridge/)
• Python syntax errors (check logs)
• Didn't restart Home Assistant after installation

Services Not Showing

Verify installation:

ls -la /config/custom_components/mcp_bridge/

Should show: __init__.py, manifest.json, services.yaml

Development

Repository Structure

homeassistant-mcp-bridge/
├── custom_components/
│   └── mcp_bridge/
│       ├── __init__.py         # Core integration logic
│       ├── manifest.json       # Integration metadata
│       ├── services.yaml       # Service definitions
│       └── test_init.py        # Unit tests
├── quick_install.sh            # One-line installer
├── install_mcp_bridge.sh       # Detailed installer
├── ha_shell_command.yaml       # HA shell command config
└── README.md                   # This file

Running Tests

pytest custom_components/mcp_bridge/test_init.py

Versioning

Check your installed version:

service: mcp_bridge.get_entity_metadata
data:
  entity_id: sensor.any_sensor  # Any entity

The response will show the integration version in logs.

Or check manifest.json:

cat /config/custom_components/mcp_bridge/manifest.json | grep version

Roadmap

• Basic entity exposure
• Script discovery with labels
• Complete metadata support
• Automated install/update script
• Real-time state updates via WebSocket
• Custom entity tags beyond voice assistant exposure
• Integration config flow (UI-based setup)
• Service call history/logging
• Version checking and update notifications

License

MIT License - Use freely in your homelab!

Support

• Issues: Report on your Gitea instance
• Logs: Settings → System → Logs (filter by "mcp_bridge")
• Questions: Check the detailed guides in the repository

Related Projects

• MCP Server: Coming next - connects to this integration
• n8n Integration: Workflow automation with AI agents

---

Made with ❤️ for home automation enthusiasts