An MCP server that exposes Home Assistant functionality to AI assistants. Built in Go, it enables AI clients like Claude, Cursor, or OpenAI to interact with your smart home through the Model Context Protocol.
Features
Entity Management: Query, search, and control Home Assistant entities
A remote MCP server for Home Assistant to control your home using AI
Stars
4
Tools
—
Uptime
—
Service Calls: Execute any Home Assistant service through the AI
System Insights: Get overviews, domain summaries, and entity history
Troubleshooting: Access error logs and automation states
Flexible Transport: Supports both stdio (local) and HTTP (remote) modes
Production Ready: Includes OAuth support, JWT validation, Dockerfile, and Helm chart
Available Tools
Tool
Description
get_version
Get the Home Assistant version
get_entity
Get state of a specific entity (with optional filtering)
entity_action
Turn entities on, off, or toggle them (with params)
list_entities
List entities with optional domain/search filters
search_entities
Search entities by name, ID, or attributes
domain_summary
Get statistics and state distribution for a domain
system_overview
Get a complete overview of the HA system
list_automations
List all automations with their states
call_service
Call any Home Assistant service (low-level API)
get_history
Get state change history for an entity
get_error_log
Retrieve the Home Assistant error log
restart_ha
Restart Home Assistant
Quick Start
Requirements
Go 1.24 or later (only for building from source)
Home Assistant instance with API access
Long-lived access token from Home Assistant
Obtaining a Home Assistant Token
Navigate to your Home Assistant instance
Click on your profile (bottom left)
Scroll to "Long-Lived Access Tokens"
Create a new token and copy it
Installation
Build from Source
git clone https://github.com/achetronic/hass-mcp.git
cd hass-mcp
make build
The binary will be created at bin/hass-mcp-{os}-{arch}.
Docker
docker pull ghcr.io/achetronic/hass-mcp:latest
Or build locally:
make docker-build IMG=your-registry/hass-mcp:latest
Configuration
Create a configuration file based on the examples in docs/:
For public-facing deployments, the server supports OAuth 2.1 with JWT validation. This enables secure access from remote AI clients like Claude Web or ChatGPT by delegating authentication to an identity provider (Keycloak, Auth0, Okta, etc.).
The server implements:
RFC 8414: OAuth Authorization Server Metadata (/.well-known/oauth-authorization-server)
Tip: If you have an upstream proxy (e.g., Istio) that validates JWTs, you can use strategy: "external" and configure forwarded_header to receive the validated JWT from the proxy.
Note: Environment variables are supported using ${VAR} syntax.
The server starts on port 8080 by default. Available endpoints depend on your configuration:
Endpoint
Description
When Enabled
/mcp
MCP protocol endpoint
Always
/.well-known/oauth-authorization-server
OAuth metadata (RFC 8414)
oauth_authorization_server.enabled: true
/.well-known/oauth-protected-resource
Protected resource metadata (RFC 9728)
oauth_protected_resource.enabled: true
Development
# Run the server
make run
# Format code
make fmt
# Run linter
make lint
# Run linter with auto-fix
make lint-fix
# Build binary
make build
# Show all available targets
make help