143 lines
3.4 KiB
Markdown
143 lines
3.4 KiB
Markdown
# 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:**
|
|
```json
|
|
{
|
|
"entities": [...],
|
|
"count": 42
|
|
}
|
|
```
|
|
|
|
### `mcp_bridge.get_exposed_scripts`
|
|
|
|
Returns all custom scripts marked with the `mcp_accessible` label.
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"scripts": [...],
|
|
"count": 1
|
|
}
|
|
```
|
|
|
|
### `mcp_bridge.get_entity_metadata`
|
|
|
|
Get detailed metadata for a specific entity.
|
|
|
|
**Parameters:**
|
|
- `entity_id` (required): The entity to query
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```yaml
|
|
# 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 |