{
  "markdown": "# AHA Model Context Protocol (MCP) Server\n\n## Quick install links\n**STDIO**  \n\n[![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)\n\n[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=aha-mcp&config=eyJjb21tYW5kIjoiZG9ja2VyIHJ1biAtLXB1bGwgYWx3YXlzIC1pIC0tcm0gLWUgVFJBTlNQT1JUPXN0ZGlvIC1lIFJFU09VUkNFU19UT19UT09MUz10cnVlIC1lIEhBU1NfVVJMPWh0dHBzOi8vaGFfaW5zdGFuY2UgLWUgSEFTU19BQ0NFU1NfVE9LRU49aGFfbG9uZ19saXZlZF9hY2Nlc3NfdG9rZW4gZ2hjci5pby9zbGhhZC9haGEtbWNwOmxhdGVzdCJ9)\n\n**Others**  \n[![smithery badge](https://smithery.ai/badge/@slhad/aha-mcp)](https://smithery.ai/server/@slhad/aha-mcp)\n\nPretty useful to test it without IDE\n\n## AHA stands for Another Home Assistant MCP Server\n\n\nThis repository implements a Model Context Protocol (MCP) server for Home Assistant, providing a bridge between Home Assistant and MCP clients.\n\nWith this server, you can:\n\n- List and query Home Assistant entities (lights, sensors, switches, etc.)\n- Retrieve and update the state of entities\n- Call Home Assistant services (e.g., turn on/off devices)\n- Manage automations: list, create, update, and validate automations\n- Access and update the entity registry\n- Integrate and update Lovelace dashboards\n- Validate Home Assistant configuration\n- Search for entities by prefix or regex\n- Access entity sources and registry information\n\nThe server supports multiple transport methods:\n- **STDIO**: Traditional MCP client communication (default)\n- **Server-Sent Events (SSE)**: Web-based real-time communication\n- **Streamable HTTP**: HTTP-based MCP communication for web integration\n\n## Table of Contents\n\n- [AHA Model Context Protocol (MCP) Server](#aha-model-context-protocol-mcp-server)\n  - [Quick install links](#quick-install-links)\n  - [AHA stands for Another Home Assistant MCP Server](#aha-stands-for-another-home-assistant-mcp-server)\n  - [Table of Contents](#table-of-contents)\n  - [Motivation](#motivation)\n  - [Features](#features)\n  - [Available Tools](#available-tools)\n    - [Generating Tools Documentation](#generating-tools-documentation)\n  - [Project Structure](#project-structure)\n  - [Example: Running the MCP Server](#example-running-the-mcp-server)\n    - [1. Run with STDIO Transport (Default)](#1-run-with-stdio-transport-default)\n    - [2. Run with Server-Sent Events (SSE) Transport](#2-run-with-server-sent-events-sse-transport)\n    - [3. Run with Streamable HTTP Transport](#3-run-with-streamable-http-transport)\n    - [4. Quick SSE Server Startup](#4-quick-sse-server-startup)\n    - [5. Run with Podman/Docker - STDIO Transport](#5-run-with-podmandocker---stdio-transport)\n    - [6. Run with Podman/Docker - HTTP/SSE Server](#6-run-with-podmandocker---httpsse-server)\n    - [Environment Variables](#environment-variables)\n  - [Getting Started](#getting-started)\n    - [Prerequisites](#prerequisites)\n    - [Installation](#installation)\n    - [Running the Server](#running-the-server)\n    - [Running Tests](#running-tests)\n    - [Docker Usage](#docker-usage)\n  - [Contributing](#contributing)\n  - [License](#license)\n\n## Motivation\n\nWhile exploring existing MCP server implementations for Home Assistant, I found that:\n\n- Many repositories did not provide a buildable or working Docker image, making deployment difficult or impossible.\n- Several projects did not actually implement the features or protocol described in their own README files.\n- Some solutions were outdated, unmaintained, or lacked clear documentation and test coverage.\n\n\nThis 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.\n\n> **Special Mention:**\n> 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.\n\n## Features\n- Home Assistant client integration\n- Entity registry and management\n- Automation and configuration MCP endpoints\n- Lovelace dashboard support\n- **Multiple transport options**: stdio, Server-Sent Events (SSE), and Streamable HTTP\n- TypeScript codebase with Vitest for testing\n- Docker support for easy deployment\n\n## Available Tools\n\nThis MCP server provides **comprehensive tools** for interacting with Home Assistant, including:\n\n- **Automation Management**: Create, update, delete, and trace automations\n- **Entity Operations**: Query and manipulate Home Assistant entities\n- **Service Calls**: Execute Home Assistant services\n- **Configuration**: Validate and manage Home Assistant configuration\n- **Registry Access**: Access entity and device registries\n- **Config Entry Flow Helpers**: Create and manage Home Assistant integration flows\n\n> **⚠️ TOKEN COST WARNING**\n>\n> **Important:** Each tool definition consumes tokens in your LLM context, even if unused! Some tools (like `update-lovelace-config`) can cost 4,000+ tokens alone. Consider excluding unnecessary tools to minimize token consumption and maximize conversation efficiency.\n\nFor a complete list of all available tools with detailed descriptions and parameters, see the **[Tools Documentation](tools.md)**.\n\n### Generating Tools Documentation\n\nThe tools documentation is automatically generated from the MCP server:\n\n```sh\nnpm run generate-docs\n```\n\nThis command will:\n1. Extract all available tools from the MCP server using the inspector\n2. Generate a comprehensive markdown documentation file (`tools.md`)\n3. Clean up temporary files\n\n**Note:** The tools documentation shows the server currently provides **39 tools** for comprehensive Home Assistant integration.\n\n## Project Structure\n- `src/` - Main source code\n  - `hass/` - Home Assistant client and helpers\n  - `server/` - MCP server implementations\n  - `mcpTransports.ts` - Transport layer implementations (HTTP, SSE)\n- `tests/` - Test files and Home Assistant config examples\n- `scripts/` - Build and documentation generation scripts\n- `Dockerfile` - Containerization support\n- `package.json` - Project dependencies and scripts\n- `tsconfig.json` - TypeScript configuration\n- `vitest.config.ts` - Vitest test runner configuration\n\n\n\n## Example: Running the MCP Server\n\nThe MCP server supports multiple transport methods. You can run it using the same command and argument structure as in your `mcp_settings.json`.\n\n### 1. Run with STDIO Transport (Default)\n\nFor traditional MCP client integration via stdio (server is launched by MCP client):\n\n```jsonc\n{\n  \"type\": \"stdio\",\n  \"command\": \"tsx\",\n  \"args\": [\n    \"c:/dev/git/aha-mcp/src/index.ts\"\n  ],\n  \"env\": {\n    \"LIMIT_RESOURCES\": \"-1\",\n    \"RESOURCES_TO_TOOLS\": \"true\",\n    \"DEBUG\": \"true\",\n    \"HASS_URL\": \"https://your-home-assistant.local:8123\",\n    \"HASS_ACCESS_TOKEN\": \"<your_token_here>\"\n  }\n}\n```\n\n### 2. Run with Server-Sent Events (SSE) Transport\n\nFor SSE-based MCP communication, you need to run the server separately and then configure the MCP client to connect via URL.\n\n**Step 1: Start the SSE server**\n```bash\n# Start the server with SSE transport using npm script\nHASS_URL=https://your-home-assistant.local:8123 HASS_ACCESS_TOKEN=<your_token_here> npm run start:local:sse\n\n# Or with additional configuration\nRESOURCES_TO_TOOLS=true DEBUG=true HASS_URL=https://your-home-assistant.local:8123 HASS_ACCESS_TOKEN=<your_token_here> npm run start:local:sse\n```\n\n**Step 2: Configure MCP client to connect via URL**\n```jsonc\n{\n  \"url\": \"http://localhost:8081/sse\",\n  \"alwaysAllow\": [\n    // your allowed tools here\n  ]\n}\n```\n\n### 3. Run with Streamable HTTP Transport\n\nFor HTTP-based MCP communication, you need to run the server separately and then configure the MCP client to connect via URL.\n\n**Step 1: Start the HTTP server**\n```bash\n# Start the server with streamable HTTP transport using npm script\nHASS_URL=https://your-home-assistant.local:8123 HASS_ACCESS_TOKEN=<your_token_here> npm run start:local:http\n```\n\n**Step 2: Configure MCP client to connect via URL**\n```jsonc\n{\n  \"url\": \"http://localhost:8081/mcp\",\n  \"alwaysAllow\": [\n    // your allowed tools here\n  ]\n}\n```\n\n### 4. Quick SSE Server Startup\n\nStart the SSE server directly with npm scripts:\n\n```bash\n# Set your Home Assistant credentials first\nexport HASS_URL=https://your-home-assistant.local:8123\nexport HASS_ACCESS_TOKEN=<your_token_here>\n\n# Start SSE server with RESOURCES_TO_TOOLS enabled\nRESOURCES_TO_TOOLS=true DEBUG=true npm run start:local:sse\n```\n\nThen configure your MCP client with:\n```jsonc\n{\n  \"url\": \"http://localhost:3000/sse\"\n}\n```\n\n### 5. Run with Podman/Docker - STDIO Transport\n\nFor STDIO transport with containers:\n\n```jsonc\n{\n  \"type\": \"stdio\",\n  \"command\": \"podman\",\n  \"args\": [\n    \"run\",\n    \"-i\",\n    \"--rm\",\n    \"-e\",\n    \"HASS_URL=https://your-home-assistant.local:8123\",\n    \"-e\",\n    \"HASS_ACCESS_TOKEN=<your_token_here>\",\n    \"ghcr.io/slhad/aha-mcp:latest\"\n  ]\n}\n```\n\n### 6. Run with Podman/Docker - HTTP/SSE Server\n\nFor HTTP/SSE transports, run the server separately in a container:\n\n**Step 1: Start the server container**\n```bash\n# For SSE transport\npodman run -p 8081:8081 -e HASS_URL=https://your-home-assistant.local:8123 -e HASS_ACCESS_TOKEN=<your_token_here> ghcr.io/slhad/aha-mcp -- sse\n\n# For HTTP transport  \npodman run -p 8081:8081 -e HASS_URL=https://your-home-assistant.local:8123 -e HASS_ACCESS_TOKEN=<your_token_here> ghcr.io/slhad/aha-mcp -- http\n```\n\n**Step 2: Configure MCP client**\n```jsonc\n{\n  \"url\": \"http://localhost:3000/sse\",  // for SSE\n  // or\n  \"url\": \"http://localhost:3000/mcp\"   // for HTTP\n}\n```\n\nReplace `<your_token_here>` with your actual Home Assistant access token.\n\n### Environment Variables\n\nThe following environment variables can be set to configure the MCP server:\n\n- `HASS_URL` (required): The URL of your Home Assistant instance. Example: `https://your-home-assistant.local:8123` (default in code: `http://localhost:8123`)\n- `HASS_ACCESS_TOKEN` (required): Long-lived access token for Home Assistant. The server will not start without this.\n- `DEBUG`: Set to `true` to enable debug logging. Default: `false`.\n- `RESOURCES_TO_TOOLS`: Set to `true` to enable mapping resources to tools. Default: `false`.\n  - **Detailed explanation:**\n    When enabled, this option exposes Home Assistant resources (such as entities, automations, and services) as individual tools for MCP clients. This is especially useful for clients or agents that can only interact with the server via tool-based interfaces, rather than through generic resource queries. It allows such clients to discover and use Home Assistant features as discrete, callable tools, improving compatibility and usability for tool-limited environments.\n- `LIMIT_RESOURCES`: Set to a number to limit the number of resources returned by the server. Default: unlimited.\n\n**Note:** The server transport method is now controlled by command line arguments (`sse` or `http`) rather than environment variables.\n\n## Getting Started\n\n### Prerequisites\n- Node.js (v18+ recommended)\n- Docker (optional, for containerized deployment)\n\n### Installation\n```sh\nnpm install\n```\n\n### Running the Server\n\n**For STDIO transport (launched by MCP client):**\n```sh\n# Set environment variables and run with npm\nnpm start\n```\n\n**For HTTP/SSE transports (run server separately):**\n```sh\n# Run SSE server on port 8081\nnpm run start:local:sse\n\n# Run HTTP server on port 8081:8081\nnpm run start:local:http\n\n# Quick SSE server startup with environment variables\nRESOURCES_TO_TOOLS=true DEBUG=true npm run start:local:sse\n```\n\nThen configure your MCP client to connect via URL:\n- SSE: `\"url\": \"http://localhost:3000/sse\"`\n- HTTP: `\"url\": \"http://localhost:8080/mcp\"`\n\n\n### Running Tests\n```sh\nnpm run test:short\n```\n\n> **Note:**\n> The unit tests currently run against a real Home Assistant instance and are not mocked yet. This means tests require a live Home Assistant server and valid credentials to execute successfully.\n\n### Docker Usage\nBuild and run the server in a Docker container:\n\n```sh\n# Build the container\nnpm run docker\n```\n\nthen follow :\n\n - [Stdio](#5-run-with-podmandocker---stdio-transport)\n - [HTTP/SSE](#6-run-with-podmandocker---httpsse-server)\n  \nFor HTTP/SSE modes, then configure your MCP client with the appropriate URL:\n- SSE: `\"url\": \"http://localhost:3000/sse\"`\n- HTTP: `\"url\": \"http://localhost:8081/mcp\"`\n\n## Contributing\nPull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.\n\n## License\nSee [LICENSE](LICENSE) for details.\n",
  "bytes": 13223,
  "sha": "7eb7cd05f17c713a32d34e33c3050bda56850325b623e72bef5eec3bc0be087f",
  "repo_slug": "slhad/aha-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_smithery_slhad_aha_mcp_a36ffe41/readme"
}