ai.smithery/slhad-aha-mcp

Install

Config snippet generator goes here (5 client tabs)

README

# AHA Model Context Protocol (MCP) Server

## Quick install links
**STDIO**  

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_AHA--MCP-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=ffffff)](https://insiders.vscode.dev/redirect/mcp/install?name=aha-mcp&config=%7B%22type%22%3A%20%22stdio%22%2C%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22--pull%22%2C%22always%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22TRANSPORT%3Dstdio%22%2C%22-e%22%2C%22RESOURCES_TO_TOOLS%3Dtrue%22%2C%22-e%22%2C%22HASS_URL%22%2C%22-e%22%2C%22HASS_ACCESS_TOKEN%22%2C%22ghcr.io%2Fslhad%2Faha-mcp%3Alatest%22%5D%2C%22env%22%3A%7B%22HASS_ACCESS_TOKEN%22%3A%22%24%7Binput%3AHASS_ACCESS_TOKEN%7D%22%2C%22HASS_URL%22%3A%22%24%7Binput%3AHASS_URL%7D%22%7D%7D)

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=aha-mcp&config=eyJjb21tYW5kIjoiZG9ja2VyIHJ1biAtLXB1bGwgYWx3YXlzIC1pIC0tcm0gLWUgVFJBTlNQT1JUPXN0ZGlvIC1lIFJFU09VUkNFU19UT19UT09MUz10cnVlIC1lIEhBU1NfVVJMPWh0dHBzOi8vaGFfaW5zdGFuY2UgLWUgSEFTU19BQ0NFU1NfVE9LRU49aGFfbG9uZ19saXZlZF9hY2Nlc3NfdG9rZW4gZ2hjci5pby9zbGhhZC9haGEtbWNwOmxhdGVzdCJ9)

**Others**  
[![smithery badge](https://smithery.ai/badge/@slhad/aha-mcp)](https://smithery.ai/server/@slhad/aha-mcp)

Pretty useful to test it without IDE

## AHA stands for Another Home Assistant MCP Server


This repository implements a Model Context Protocol (MCP) server for Home Assistant, providing a bridge between Home Assistant and MCP clients.

With this server, you can:

- List and query Home Assistant entities (lights, sensors, switches, etc.)
- Retrieve and update the state of entities
- Call Home Assistant services (e.g., turn on/off devices)
- Manage automations: list, create, update, and validate automations
- Access and update the entity registry
- Integrate and update Lovelace dashboards
- Validate Home Assistant configuration
- Search for entities by prefix or regex
- Access entity sources and registry information

The server supports multiple transport methods:
- **STDIO**: Traditional MCP client communication (default)
- **Server-Sent Events (SSE)**: Web-based real-time communication
- **Streamable HTTP**: HTTP-based MCP communication for web integration

## Table of Contents

- [AHA Model Context Protocol (MCP) Server](#aha-model-context-protocol-mcp-server)
  - [Quick install links](#quick-install-links)
  - [AHA stands for Another Home Assistant MCP Server](#aha-stands-for-another-home-assistant-mcp-server)
  - [Table of Contents](#table-of-contents)
  - [Motivation](#motivation)
  - [Features](#features)
  - [Available Tools](#available-tools)
    - [Generating Tools Documentation](#generating-tools-documentation)
  - [Project Structure](#project-structure)
  - [Example: Running the MCP Server](#example-running-the-mcp-server)
    - [1. Run with STDIO Transport (Default)](#1-run-with-stdio-transport-default)
    - [2. Run with Server-Sent Events (SSE) Transport](#2-run-with-server-sent-events-sse-transport)
    - [3. Run with Streamable HTTP Transport](#3-run-with-streamable-http-transport)
    - [4. Quick SSE Server Startup](#4-quick-sse-server-startup)
    - [5. Run with Podman/Docker - STDIO Transport](#5-run-with-podmandocker---stdio-transport)
    - [6. Run with Podman/Docker - HTTP/SSE Server](#6-run-with-podmandocker---httpsse-server)
    - [Environment Variables](#environment-variables)
  - [Getting Started](#getting-started)
    - [Prerequisites](#prerequisites)
    - [Installation](#installation)
    - [Running the Server](#running-the-server)
    - [Running Tests](#running-tests)
    - [Docker Usage](#docker-usage)
  - [Contributing](#contributing)
  - [License](#license)

## Motivation

While exploring existing MCP server implementations for Home Assistant, I found that:

- Many repositories did not provide a buildable or working Docker image, making deployment difficult or impossible.
- Several projects did not actually implement the features or protocol described in their own README files.
- Some solutions were outdated, unmaintained, or lacked clear documentation and test coverage.


This project aims to address these gaps by providing a reliable and fully functional MCP server with straightforward Docker support and a focus on real-world usability.

> **Special Mention:**
> Most of the documentation in this project is generated or assisted by AI. As this is a side project (even though I work as a developer), I focus on building fun and working features, and prefer to review and accept generated documentation if it's good enough, rather than writing everything by hand.

## Features
- Home Assistant client integration
- Entity registry and management
- Automation and configuration MCP endpoints
- Lovelace dashboard support
- **Multiple transport options**: stdio, Server-Sent Events (SSE), and Streamable HTTP
- TypeScript codebase with Vitest for testing
- Docker support for easy deployment

## Available Tools

This MCP s