🎯 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

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
Copy to /config/custom_components/mcp_bridge/
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:

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
        }
      }
    }
  ],
  "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:

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
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

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

Made with ❤️ for home automation enthusiasts

README.md

MCP Bridge - Home Assistant Integration

Features