mvezina/homeassistant-mcp-bridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[MOD] New installation method since HACS does not support GITEA

Browse Source
This commit is contained in:
Martin 2026-02-10 15:23:14 -05:00
parent a826ef80ec
commit ae56716a86
6 changed files with 145 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

194
README.md
View File

@ -1,7 +1,5 @@
# MCP Bridge - Home Assistant Integration # 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. Bridge integration between Home Assistant and MCP (Model Context Protocol) servers, enabling AI agents to control your smart home.
## Features ## Features
@ -18,29 +16,79 @@ MCP (Model Context Protocol) is Anthropic's protocol for connecting AI agents to
## Installation ## Installation
### Via HACS (Recommended) **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.
1. **Add Custom Repository** ### Method 1: One-Line Install/Update (Easiest)
- 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** Run this command in your Home Assistant terminal (requires Terminal & SSH addon or SSH access):
- HACS → Integrations
- Click "+ Explore & Download Repositories"
- Search for "MCP Bridge"
- Click "Download"
- Restart Home Assistant
### Manual Installation ```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
```
1. Copy `custom_components/mcp_bridge` to your Home Assistant config directory **Important:**
2. Restart Home Assistant - Replace `your-gitea.local:3000` with your Gitea server address
- Replace `username` with your Gitea username
- Replace `main` with your branch name if different
See [INSTALLATION_GUIDE.md](INSTALLATION_GUIDE.md) for detailed instructions. 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 ## Quick Start
@ -108,8 +156,7 @@ Returns scripts marked with `mcp_accessible` label, including their parameters.
"speed": { "speed": {
"name": "Speed", "name": "Speed",
"description": "0=off, 1=low, 2=medium, 3=high", "description": "0=off, 1=low, 2=medium, 3=high",
"required": true, "required": true
"selector": {"number": {"min": 0, "max": 3}}
} }
} }
} }
@ -125,6 +172,17 @@ Get detailed metadata for a specific entity.
**Parameters:** **Parameters:**
- `entity_id`: The entity to query - `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 ## Architecture
``` ```
@ -160,24 +218,46 @@ No configuration required! The integration automatically loads on Home Assistant
## Compatibility ## Compatibility
- **Home Assistant**: 2024.1.0 or newer - **Home Assistant**: 2024.1.0 or newer
- **HACS**: Any version
- **Python**: 3.11+ - **Python**: 3.11+
- **Installation**: Requires SSH/Terminal access or manual file management
## Documentation ## Troubleshooting
- [Installation Guide](INSTALLATION_GUIDE.md) - Detailed setup instructions ### Installation Script Fails
- [Integration README](custom_components/mcp_bridge/README.md) - Technical details
- [Gitea Setup Guide](GITEA_SETUP_GUIDE.md) - For hosting on your own Gitea **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 ## Development
### Running Tests ### Repository Structure
```bash
pytest custom_components/mcp_bridge/test_init.py
```
### Project Structure
``` ```
homeassistant-mcp-bridge/ homeassistant-mcp-bridge/
@ -186,31 +266,46 @@ homeassistant-mcp-bridge/
│ ├── __init__.py # Core integration logic │ ├── __init__.py # Core integration logic
│ ├── manifest.json # Integration metadata │ ├── manifest.json # Integration metadata
│ ├── services.yaml # Service definitions │ ├── services.yaml # Service definitions
│ └── README.md # Integration docs │ └── test_init.py # Unit tests
├── hacs.json # HACS configuration ├── quick_install.sh # One-line installer
├── info.md # HACS UI description ├── install_mcp_bridge.sh # Detailed installer
└── README.md # This file ├── ha_shell_command.yaml # HA shell command config
└── README.md # This file
``` ```
## Contributing ### Running Tests
This is a personal project for homelab use, but suggestions and improvements are welcome! ```bash
pytest custom_components/mcp_bridge/test_init.py
```
1. Fork the repository ## Versioning
2. Create a feature branch
3. Make your changes Check your installed version:
4. Test thoroughly ```yaml
5. Submit a pull request 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 ## Roadmap
- [x] Basic entity exposure - [x] Basic entity exposure
- [x] Script discovery with labels - [x] Script discovery with labels
- [x] Complete metadata support - [x] Complete metadata support
- [x] Automated install/update script
- [ ] Real-time state updates via WebSocket - [ ] Real-time state updates via WebSocket
- [ ] Custom entity tags beyond voice assistant exposure - [ ] Custom entity tags beyond voice assistant exposure
- [ ] Integration config flow (UI-based setup) - [ ] Integration config flow (UI-based setup)
- [ ] Service call history/logging - [ ] Service call history/logging
- [ ] Version checking and update notifications
## License ## License
@ -218,13 +313,14 @@ MIT License - Use freely in your homelab!
## Support ## Support
- **Issues**: [Gitea Issues](http://your-gitea-server/username/homeassistant-mcp-bridge/issues) - **Issues**: Report on your Gitea instance
- **Logs**: Settings → System → Logs (filter by "mcp_bridge") - **Logs**: Settings → System → Logs (filter by "mcp_bridge")
- **Questions**: Check the detailed guides in the repository
## Acknowledgments ## Related Projects
- Built for use with [Anthropic's MCP](https://modelcontextprotocol.io/) - **MCP Server**: Coming next - connects to this integration
- Designed to work with n8n workflows - **n8n Integration**: Workflow automation with AI agents
--- ---

0
ha_shell_command.yaml Normal file
View File

5
hacs.json
View File

@ -1,5 +0,0 @@
{
"name": "MCP Bridge",
"content_in_root": false,
"homeassistant": "2024.1.0"
}

35
info.md
View File

@ -1,35 +0,0 @@
# MCP Bridge
Bridge integration between Home Assistant and MCP (Model Context Protocol) servers for AI agent control.
## Features
- ✅ Expose entities to AI agents via voice assistant settings
- ✅ Control which scripts are accessible using labels
- ✅ Complete entity metadata including area, device class, and attributes
- ✅ Secure: Only exposes what you explicitly mark
## Services
- `mcp_bridge.get_exposed_entities` - Get all exposed entities
- `mcp_bridge.get_exposed_scripts` - Get MCP-accessible scripts
- `mcp_bridge.get_entity_metadata` - Get detailed entity info
## Configuration
No configuration needed! The integration auto-loads after installation.
### Exposing Entities
Go to: **Settings → Voice Assistants → Expose**
Toggle the entities you want the AI agent to control.
### Exposing Scripts
1. Create or edit a script
2. Click the settings icon ⚙️
3. Add the label: `mcp_accessible`
4. Save
That's it! The script is now accessible to AI agents.

0
install_mcp_bridge.sh Normal file
View File

0
quick_install.sh Normal file
View File