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

```bash
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:

```yaml
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:**
```yaml
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](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:**

```yaml
service: mcp_bridge.get_exposed_entities
```

```yaml
service: mcp_bridge.get_exposed_scripts
```

## Services

### `mcp_bridge.get_exposed_entities`

Returns all entities exposed to voice assistants with complete metadata.

**Example Response:**
```json
{
  "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:**
```json
{
  "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:**
```bash
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:**
```bash
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

```bash
pytest custom_components/mcp_bridge/test_init.py
```

## Versioning

Check your installed version:
```yaml
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`:
```bash
cat /config/custom_components/mcp_bridge/manifest.json | grep version
```

## Roadmap

- [x] Basic entity exposure
- [x] Script discovery with labels
- [x] Complete metadata support
- [x] 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**