Slhad Aha Mcp

ai.smitheryPublished by smithery.aiOfficial publisherv0.1.0Updated Oct 24, 2026

A TypeScript MCP server for Home Assistant, enabling programmatic management of entities, automati…

The publisher's own server: 222wcnm Bilistalkermcp

VerifiedStreamable HTTPWeb executableProductivity & WorkflowDeveloper ToolsSecurity & Monitoring

Overview

AI-generated overview

Lets an assistant query and control Home Assistant entities, call services, and manage automations, dashboards and configuration.

What you can do
A TypeScript MCP server that bridges Home Assistant and MCP clients (R5). It lists and searches entities, retrieves and updates their state, and calls Home Assistant services such as turning devices on or off (R7-R9, R14). It also manages automations (list, create, update, delete, trace, validate), accesses entity and device registries, updates Lovelace dashboards, validates configuration, and helps with integration config flows (R10-R13, R39-R44). It supports stdio, SSE and Streamable HTTP transports (R17-R19).
When to use it
Use it when you want an assistant to inspect or operate a Home Assistant setup in natural language: checking sensor and switch states, toggling devices, or drafting and validating automations and dashboards. It suits users who already run Home Assistant and want tool-based access from an MCP client rather than manual UI work. It is less useful if you do not have a Home Assistant instance to connect to.
Requirements
A running Home Assistant instance reachable at HASS_URL and a long-lived access token in HASS_ACCESS_TOKEN; the server will not start without the token (R95, R96). Node.js v18 or newer for local runs, or Docker/Podman for containerized deployment (R109, R110). Optional variables: DEBUG, RESOURCES_TO_TOOLS, LIMIT_RESOURCES (R97-R105). The remote Smithery endpoint requires an Authorization bearer token header (V1.1).
Before you install
The server needs a Home Assistant long-lived access token (HASS_ACCESS_TOKEN) that grants broad control of the instance, so treat it as a sensitive secret. Tools can change state, call services, and create, update or delete automations and dashboards (R8, R9, R10, R39), so unintended writes are possible. Tool definitions consume LLM context tokens, with some costing thousands each (R46, R47). The README notes documentation is largely AI-generated (R27).

Installation

In SourceWeft

  1. Open Slhad Aha Mcp in the dashboard and add it to a workspace.
  2. Connect Authorization token credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/ai.smithery%2Fslhad-aha-mcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "slhad-aha": {
      "type": "http",
      "url": "https://server.smithery.ai/@slhad/aha-mcp/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

README

AHA Model Context Protocol (MCP) Server

Quick install links

STDIO

[Install in VS Code]

[Install MCP Server]

Others
[smithery badge]

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

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 server provides comprehensive tools for interacting with Home Assistant, including:

  • Automation Management: Create, update, delete, and trace automations
  • Entity Operations: Query and manipulate Home Assistant entities
  • Service Calls: Execute Home Assistant services
  • Configuration: Validate and manage Home Assistant configuration
  • Registry Access: Access entity and device registries
  • Config Entry Flow Helpers: Create and manage Home Assistant integration flows

⚠️ TOKEN COST WARNING

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.

For a complete list of all available tools with detailed descriptions and parameters, see the Tools Documentation.

Generating Tools Documentation

The tools documentation is automatically generated from the MCP server:

sh
npm run generate-docs

This command will:

  1. Extract all available tools from the MCP server using the inspector
  2. Generate a comprehensive markdown documentation file (tools.md)
  3. Clean up temporary files

Note: The tools documentation shows the server currently provides 39 tools for comprehensive Home Assistant integration.

Project Structure

  • src/ - Main source code
    • hass/ - Home Assistant client and helpers
    • server/ - MCP server implementations
    • mcpTransports.ts - Transport layer implementations (HTTP, SSE)
  • tests/ - Test files and Home Assistant config examples
  • scripts/ - Build and documentation generation scripts
  • Dockerfile - Containerization support
  • package.json - Project dependencies and scripts
  • tsconfig.json - TypeScript configuration
  • vitest.config.ts - Vitest test runner configuration

Example: Running the MCP Server

The MCP server supports multiple transport methods. You can run it using the same command and argument structure as in your mcp_settings.json.

1. Run with STDIO Transport (Default)

For traditional MCP client integration via stdio (server is launched by MCP client):

jsonc
{  "type": "stdio",  "command": "tsx",  "args": [    "c:/dev/git/aha-mcp/src/index.ts"  ],  "env": {    "LIMIT_RESOURCES": "-1",    "RESOURCES_TO_TOOLS": "true",    "DEBUG": "true",    "HASS_URL": "https://your-home-assistant.local:8123",    "HASS_ACCESS_TOKEN": "<your_token_here>"  }}

2. Run with Server-Sent Events (SSE) Transport

For SSE-based MCP communication, you need to run the server separately and then configure the MCP client to connect via URL.

Step 1: Start the SSE server

bash
# Start the server with SSE transport using npm scriptHASS_URL=https://your-home-assistant.local:8123 HASS_ACCESS_TOKEN=<your_token_here> npm run start:local:sse
# Or with additional configurationRESOURCES_TO_TOOLS=true DEBUG=true HASS_URL=https://your-home-assistant.local:8123 HASS_ACCESS_TOKEN=<your_token_here> npm run start:local:sse

Step 2: Configure MCP client to connect via URL

jsonc
{  "url": "http://localhost:8081/sse",  "alwaysAllow": [    // your allowed tools here  ]}

3. Run with Streamable HTTP Transport

For HTTP-based MCP communication, you need to run the server separately and then configure the MCP client to connect via URL.

Step 1: Start the HTTP server

bash
# Start the server with streamable HTTP transport using npm scriptHASS_URL=https://your-home-assistant.local:8123 HASS_ACCESS_TOKEN=<your_token_here> npm run start:local:http

Step 2: Configure MCP client to connect via URL

jsonc
{  "url": "http://localhost:8081/mcp",  "alwaysAllow": [    // your allowed tools here  ]}

4. Quick SSE Server Startup

Start the SSE server directly with npm scripts:

bash
# Set your Home Assistant credentials firstexport HASS_URL=https://your-home-assistant.local:8123export HASS_ACCESS_TOKEN=<your_token_here>
# Start SSE server with RESOURCES_TO_TOOLS enabledRESOURCES_TO_TOOLS=true DEBUG=true npm run start:local:sse

Then configure your MCP client with:

jsonc
{  "url": "http://localhost:3000/sse"}

5. Run with Podman/Docker - STDIO Transport

For STDIO transport with containers:

jsonc
{  "type": "stdio",  "command": "podman",  "args": [    "run",    "-i",    "--rm",    "-e",    "HASS_URL=https://your-home-assistant.local:8123",    "-e",    "HASS_ACCESS_TOKEN=<your_token_here>",    "ghcr.io/slhad/aha-mcp:latest"  ]}

6. Run with Podman/Docker - HTTP/SSE Server

For HTTP/SSE transports, run the server separately in a container:

Step 1: Start the server container

bash
# For SSE transportpodman 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
# For HTTP transport  podman 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

Step 2: Configure MCP client

jsonc
{  "url": "http://localhost:3000/sse",  // for SSE  // or  "url": "http://localhost:3000/mcp"   // for HTTP}

Replace <your_token_here> with your actual Home Assistant access token.

Environment Variables

The following environment variables can be set to configure the MCP server:

  • HASS_URL (required): The URL of your Home Assistant instance. Example: https://your-home-assistant.local:8123 (default in code: http://localhost:8123)
  • HASS_ACCESS_TOKEN (required): Long-lived access token for Home Assistant. The server will not start without this.
  • DEBUG: Set to true to enable debug logging. Default: false.
  • RESOURCES_TO_TOOLS: Set to true to enable mapping resources to tools. Default: false.
    • Detailed explanation: 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.
  • LIMIT_RESOURCES: Set to a number to limit the number of resources returned by the server. Default: unlimited.

Note: The server transport method is now controlled by command line arguments (sse or http) rather than environment variables.

Getting Started

Prerequisites

  • Node.js (v18+ recommended)
  • Docker (optional, for containerized deployment)

Installation

sh
npm install

Running the Server

For STDIO transport (launched by MCP client):

sh
# Set environment variables and run with npmnpm start

For HTTP/SSE transports (run server separately):

sh
# Run SSE server on port 8081npm run start:local:sse
# Run HTTP server on port 8081:8081npm run start:local:http
# Quick SSE server startup with environment variablesRESOURCES_TO_TOOLS=true DEBUG=true npm run start:local:sse

Then configure your MCP client to connect via URL:

  • SSE: "url": "http://localhost:3000/sse"
  • HTTP: "url": "http://localhost:8080/mcp"

Running Tests

sh
npm run test:short

Note: 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.

Docker Usage

Build and run the server in a Docker container:

sh
# Build the containernpm run docker

then follow :

For HTTP/SSE modes, then configure your MCP client with the appropriate URL:

  • SSE: "url": "http://localhost:3000/sse"
  • HTTP: "url": "http://localhost:8081/mcp"

Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

License

See LICENSE for details.

Source: README.md at commit a212cba

Tools

0
SourceWeft has not read this server's tools yet.

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

85% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Smithery integrations

222wcnm Bilistalkermcp

ai.smitheryOfficial publisher

Bilibili creator analysis server that lets an assistant look up a specific user's profile, videos, dynamics, articles, subtitles, followings and comments.

Streamable HTTPWeb executable
Knowledge & MemoryNot indexed yetOct 24, 2026

Zwldarren Akshare One Mcp

ai.smitheryOfficial publisher

Remote MCP server that gives an assistant read-only access to Chinese stock market data: historical and real-time prices, news, and financial statements.

Streamable HTTPWeb executableAuth
FinanceCredential requiredOct 24, 2026

Zhaoganghao Hellomcp

ai.smitheryOfficial publisher

A small remote MCP server that lets an assistant greet people by name and share background on the origin of 'Hello, World'.

Streamable HTTPWeb executable
Not indexed yetOct 24, 2026

Zeta Chain Cli

ai.smitheryOfficial publisher

A remote MCP server that lets an assistant generate friendly, customizable greetings for any name or audience.

Streamable HTTPWeb executableAuth
Credential requiredOct 24, 2026

Yuna0x0 Hackmd Mcp

ai.smitheryOfficial publisher

An MCP server that connects an assistant to the HackMD API so it can read, create, update and delete HackMD notes and manage teams.

Streamable HTTPWeb executable
Communication & CollaborationNot indexed yetOct 25, 2026