AHA Model Context Protocol (MCP) Server

Quick install links

STDIO

Others

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
  • Quick install links
  • AHA stands for Another Home Assistant MCP Server
  • Table of Contents
  • Motivation
  • Features
  • Available Tools
    • Generating Tools Documentation
  • Project Structure
  • Example: Running the MCP Server
    • 1. Run with STDIO Transport (Default)
    • 2. Run with Server-Sent Events (SSE) Transport
    • 3. Run with Streamable HTTP Transport
    • 4. Quick SSE Server Startup
    • 5. Run with Podman/Docker - STDIO Transport
    • 6. Run with Podman/Docker - HTTP/SSE Server
    • Environment Variables
  • Getting Started
    • Prerequisites
    • Installation
    • Running the Server
    • Running Tests
    • Docker Usage
  • Contributing
  • 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 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:

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):

{
  "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

# Start the server with SSE transport using npm script
HASS_URL=https://your-home-assistant.local:8123 HASS_ACCESS_TOKEN=<your_token_here> npm run start:local:sse

# Or with additional configuration
RESOURCES_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

{
  "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

# Start the server with streamable HTTP transport using npm script
HASS_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

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

4. Quick SSE Server Startup

Start the SSE server directly with npm scripts:

# Set your Home Assistant credentials first
export HASS_URL=https://your-home-assistant.local:8123
export HASS_ACCESS_TOKEN=<your_token_here>

# Start SSE server with RESOURCES_TO_TOOLS enabled
RESOURCES_TO_TOOLS=true DEBUG=true npm run start:local:sse

Then configure your MCP client with:

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

5. Run with Podman/Docker - STDIO Transport

For STDIO transport with containers:

{
  "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

# For SSE 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 -- sse