# Homeassistant Mcp Server

> Comprehensive Home Assistant MCP Server with 60 tools for AI-driven smart home control including SSH/SFTP file management. Production-ready k3s deployment for Pi4 cluster.

- **Type:** MCP server
- **Install:** `agentstack add mcp-agarib-homeassistant-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [agarib](https://agentstack.voostack.com/s/agarib)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [agarib](https://github.com/agarib)
- **Source:** https://github.com/agarib/homeassistant-mcp-server

## Install

```sh
agentstack add mcp-agarib-homeassistant-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Home Assistant OpenAPI Server

[](https://github.com/agarib/homeassistant-mcp-server/releases)
[](https://www.home-assistant.io/)
[](LICENSE)

Production-ready REST API server with **97 unified endpoints** for complete Home Assistant control. Perfect for AI assistants, automation platforms, and custom integrations.

## ✨ Features

- **97 Production Endpoints** - Complete coverage of HA functionality (100% success rate)
- **Zero Configuration** - Auto-discovers SUPERVISOR_TOKEN from s6-overlay
- **Full REST API** - All operations via POST/GET with Pydantic validation
- **WebSocket Support** - Real-time dashboard and Lovelace operations
- **AI Assistant Ready** - OpenAPI spec for LLM tool integration
- **MCP Compatible** - Works with Model Context Protocol servers (MCPO, Claude Desktop, etc.)

## 🚀 Quick Start

### Installation

1. **Add Repository to Home Assistant:**
   ```
   https://github.com/agarib/homeassistant-mcp-server
   ```

2. **Install the Add-on:**
   - Navigate to **Settings** → **Add-ons** → **Add-on Store**
   - Find "Home Assistant OpenAPI Server" in available add-ons
   - Click **Install**

3. **Start the Add-on:**
   - Click **Start**
   - API will be available at `http://homeassistant.local:8001`

### Configuration

Minimal configuration required:

```yaml
port: 8001           # HTTP port (default: 8001)
log_level: info      # Log level (debug|info|warning|error|critical)
```

**Note:** Authentication is handled automatically via Home Assistant's Supervisor token injection.

## 📚 API Documentation

Access interactive documentation once the addon is running:

- **Swagger UI:** `http://homeassistant.local:8001/`
- **OpenAPI Spec:** `http://homeassistant.local:8001/openapi.json`
- **Health Check:** `http://homeassistant.local:8001/health`

### Example API Calls

```bash
# Get entity states
curl -X POST http://homeassistant.local:8001/ha_get_states \
  -H "Content-Type: application/json" \
  -d '{"limit": 5}'

# Control a light
curl -X POST http://homeassistant.local:8001/ha_control_light \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "light.living_room", "action": "turn_on", "brightness": 255}'

# Discover devices
curl -X POST http://homeassistant.local:8001/ha_discover_devices \
  -H "Content-Type: application/json" \
  -d '{"domain": "light"}'
```

## 🛠️ Endpoint Categories

| Category           | Count | Description                         |
| ------------------ | ----- | ----------------------------------- |
| Core HA API        | 8     | Entity states, services, events     |
| System Diagnostics | 6     | Logs, notifications, health checks  |
| Integrations       | 3     | Config entries, device diagnostics  |
| Advanced API       | 3     | Templates, intents, validation      |
| Automations        | 8     | Create, update, trigger, reload     |
| File Operations    | 10    | Full `/config` directory access     |
| Add-on Management  | 9     | Install, start, stop, logs          |
| Dashboards         | 12    | Lovelace management, HACS cards     |
| Device Control     | 7     | Lights, switches, climate, covers   |
| Logs & History     | 6     | Entity history, diagnostics         |
| Discovery          | 4     | States, areas, devices, entities    |
| Intelligence       | 4     | Context, activity, comfort analysis |
| Code Execution     | 3     | Python sandbox with pandas          |
| Scenes             | 3     | Activate, create, list              |
| Security           | 3     | Monitoring, anomaly detection       |
| Camera VLM         | 3     | Vision AI analysis                  |
| System             | 3     | Restart, service calls              |
| Camera             | 1     | Snapshots                           |
| Utility            | 2     | Health check, API info              |

**Option B: Using SSH/SFTP** (If available)

```powershell
# Using SCP
scp -r "C:\MyProjects\ha-mcp-server-addon" root@192.168.1.203:/config/addons/local/ha-mcp-server
```

## 🔧 Technical Details

### Architecture

- **Runtime:** Python 3 with FastAPI + Uvicorn
- **Authentication:** Automatic SUPERVISOR_TOKEN via s6-overlay
- **Validation:** Pydantic models for all requests/responses
- **API Style:** RESTful with OpenAPI 3.0 specification
- **Persistence:** Reads directly from `/config` directory

### Requirements

- Home Assistant OS or Supervised install (requires Supervisor)
- Home Assistant 2025.11 or newer
- Architecture: aarch64, amd64, armv7, armhf, i386

### Token Authentication

The addon automatically retrieves the SUPERVISOR_TOKEN from Home Assistant's s6-overlay environment store (`/var/run/s6/container_environment/`). No manual token configuration required.

## 🐛 Troubleshooting

### Common Issues

**401 Unauthorized Errors:**
- Verify the addon is running: Check addon logs for "✅ Loaded SUPERVISOR_TOKEN"
- Ensure you're using `http://homeassistant.local:8001` (not https)
- Check Home Assistant version is 2025.11+

**Addon Won't Start:**
- Check addon logs via Settings → Add-ons → Home Assistant OpenAPI Server → Log
- Verify `/config/ha-openapi-server/server.py` exists and is readable
- Try rebuilding: Settings → Add-ons → Home Assistant OpenAPI Server → Rebuild

**API Endpoints Return Errors:**
- Verify Home Assistant core is running
- Check entity IDs exist: `/ha_get_states` endpoint
- Review addon logs for detailed error messages

## 📋 Version History

### v4.0.27 (2025-12-03) - Current

- **FIXED:** SUPERVISOR_TOKEN injection via s6-overlay environment store
- **FIXED:** Authentication now works without bashio dependency
- **Added:** Automatic token fallback mechanism (SUPERVISOR_TOKEN → HASSIO_TOKEN)
- **Enhanced:** Debug logging for s6-overlay environment troubleshooting
- **Result:** 97/97 endpoints working (100% success rate restored)

### v4.0.21 (2025-12-02)

- Fixed addon installation and startup issues
- Removed bashio dependency (BOM encoding fixes)
- Unified folder structure to `ha-openapi-server`
- Complete YAML configuration for GitHub deployment

### v4.0.14 (2025-11-13)

- Initial stable release with 97 unified endpoints
- WebSocket support for dashboard operations
- Full OpenAPI specification generated

## 🤝 Integration Examples

### Use with Open-WebUI

Add as an external tool:

```text
URL: http://homeassistant.local:8001/openapi.json
Type: OpenAPI
```

### Use with MCP Server

Configure in MCPO settings:

```json
{
  "homeassistant": {
    "command": "curl",
    "args": ["-s", "http://homeassistant.local:8001/openapi.json"]
  }
}
```

## 📞 Support

- **Issues:** [GitHub Issues](https://github.com/agarib/homeassistant-mcp-server/issues)
- **Discussions:** [GitHub Discussions](https://github.com/agarib/homeassistant-mcp-server/discussions)
- **Documentation:** [Full Changelog](CHANGELOG.md)

## 📄 License

MIT License - See [LICENSE](LICENSE) file for details

---

**Version:** 4.0.27  
**Author:** agarib  
**Repository:** https://github.com/agarib/homeassistant-mcp-server

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [agarib](https://github.com/agarib)
- **Source:** [agarib/homeassistant-mcp-server](https://github.com/agarib/homeassistant-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-agarib-homeassistant-mcp-server
- Seller: https://agentstack.voostack.com/s/agarib
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.