homeassistant-mcp-bridge/custom_components/mcp_bridge

MCP Bridge - Home Assistant Custom Integration

This integration provides services to expose filtered entities and custom scripts to MCP (Model Context Protocol) servers, enabling AI agents to control your Home Assistant instance.

Installation

Via HACS (Recommended)

1. Install HACS (if not already installed): https://hacs.xyz/docs/setup/download

2. Add this repository as a custom repository:

   • Open HACS in Home Assistant
   • Click the three dots in the top right
   • Select "Custom repositories"
   • Add your Gitea URL: http://your-gitea-server/username/homeassistant-mcp-bridge
   • Category: Integration
   • Click "Add"

3. Install the integration:

   • Go to HACS → Integrations
   • Click "+ Explore & Download Repositories"
   • Search for "MCP Bridge"
   • Click "Download"
   • Restart Home Assistant

Manual Installation

1. Copy the mcp_bridge folder to your Home Assistant custom_components directory:

   /config/custom_components/mcp_bridge/
   

2. Restart Home Assistant

3. The integration will be automatically loaded (no configuration needed)

Services

mcp_bridge.get_exposed_entities

Returns all entities that are exposed to voice assistants.

Returns:

{
  "entities": [...],
  "count": 42
}

mcp_bridge.get_exposed_scripts

Returns all custom scripts marked with the mcp_accessible label.

Returns:

{
  "scripts": [...],
  "count": 1
}

mcp_bridge.get_entity_metadata

Get detailed metadata for a specific entity.

Parameters:

• entity_id (required): The entity to query

Returns:

{
  "entity_id": "light.living_room",
  "state": "on",
  ...
}

Usage

Exposing Entities to AI Agent

1. Go to Settings → Voice Assistants → Expose
2. Toggle entities you want the AI agent to control
3. These entities will be returned by mcp_bridge.get_exposed_entities

Exposing Scripts to AI Agent

1. Create your custom script in HA
2. Add the label mcp_accessible to the script:
   • Go to Settings → Automations & Scenes → Scripts
   • Click on your script
   • Click the settings icon (top right)
   • Under "Labels", add mcp_accessible
3. The script will now be returned by mcp_bridge.get_exposed_scripts

Example: Marking a Script as MCP-Accessible

# In your scripts.yaml or via UI
set_master_bedroom_fan_speed:
  alias: "Set Master Bedroom Fan Speed"
  description: "[MCP] Set the speed of the master bedroom fan."
  # Add label via UI: Settings → Scripts → (your script) → Labels → mcp_accessible
  fields:
    fan_state:
      name: Fan speed
      description: "0=off, 1=low, 2=medium, 3=high"
      required: true
      selector:
        number:
          min: 0
          max: 3
          step: 1
  sequence:
    # Your script actions here

Testing

You can test the services in Home Assistant's Developer Tools → Services:

1. Select mcp_bridge.get_exposed_entities
2. Click "Call Service"
3. View the response in the "Response" tab

Troubleshooting

No entities returned:

• Make sure you've exposed entities via Settings → Voice Assistants → Expose

No scripts returned:

• Ensure your scripts have the mcp_accessible label
• Check Home Assistant logs for errors: Settings → System → Logs

Integration not loading:

• Check the logs for errors
• Ensure the folder structure is correct
• Restart Home Assistant

Version

0.1.0 - Initial release