homeassistant-mcp-bridge/README.md

# MCP Bridge - Home Assistant Integration

[![hacs_badge](https://img.shields.io/badge/HACS-Custom-orange.svg)](https://github.com/custom-components/hacs)

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)

1. **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"

2. **Install**
   - HACS → Integrations
   - Click "+ Explore & Download Repositories"
   - Search for "MCP Bridge"
   - Click "Download"
   - Restart Home Assistant

### Manual Installation

1. Copy `custom_components/mcp_bridge` to your Home Assistant config directory
2. Restart Home Assistant

See [INSTALLATION_GUIDE.md](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:
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,
          "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:
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
- **HACS**: Any version
- **Python**: 3.11+

## Documentation

- [Installation Guide](INSTALLATION_GUIDE.md) - Detailed setup instructions
- [Integration README](custom_components/mcp_bridge/README.md) - Technical details
- [Gitea Setup Guide](GITEA_SETUP_GUIDE.md) - For hosting on your own Gitea

## Development

### Running Tests

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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

## Roadmap

- [x] Basic entity exposure
- [x] Script discovery with labels
- [x] 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](http://your-gitea-server/username/homeassistant-mcp-bridge/issues)
- **Logs**: Settings → System → Logs (filter by "mcp_bridge")

## Acknowledgments

- Built for use with [Anthropic's MCP](https://modelcontextprotocol.io/)
- Designed to work with n8n workflows

---

**Made with ❤️ for home automation enthusiasts**