A Home Assistant Custom Component that provides an MCP (Model Context Protocol) server using , allowing AI assistants like Claude to interact with your Home Assistant instance.
概要
A Home Assistant Custom Component that provides an MCP (Model Context Protocol) server using , allowing AI assistants like Claude to interact with your Home Assistant instance.
README
MCP Server for Home Assistant (HTTP Transport)
A Home Assistant Custom Component that provides an MCP (Model Context Protocol) server using HTTP transport, allowing AI assistants like Claude to interact with your Home Assistant instance.
Why HTTP transport with OAuth? This project was built primarily to support MCP Streamable HTTP transport, enabling web-based clients like Claude that require OIDC and OAuth 2.0 Dynamic Client Registration (RFC 7591). Since Home Assistant already has an official MCP integration that supports SSE transport, there wasn’t a need to duplicate that. For local or custom client setups, Long-Lived Access Token authentication can be enabled as an alternative.
Features
- 🌐 HTTP transport (not SSE) - works remotely, not just locally
- 🔐 OAuth 2.0 authentication with Dynamic Client Registration (via hass-oidc-server)
- 🔑 Long-Lived Access Token authentication (opt-in) for local and custom client setups
- 🏠 Full Home Assistant API access (entities, services, areas, devices, history, statistics)
- 🔧 Easy HACS installation
- 📝 CRUD management of automations, scenes, scripts, and helper entities (input_boolean, counter, timer, schedule, and more)
- 🔍 Automation & script traces — inspect why a run fired, didn’t fire, or took the wrong branch, step by step (read-only)
- 📋 Lovelace dashboard management (list, get/save/delete config, create/update/delete dashboards) with outline reads and JSON Patch edits so a single card can be changed without resending the whole dashboard
- 🩺 System administration tools (error log, config validation, restart, system status)
- 📁 YAML config file management — read, write, delete files with automatic backup before every change and built-in config validation (opt-in)
- 📷 Camera & image access — capture live camera frames and read saved image files for visual analysis (opt-in)
- 📊 Resources, prompts, and completions for richer AI interactions
- 🧹 Optimization prompts for auditing automations, naming conventions, and scheduling
Prerequisites
The integration supports two authentication methods:
- OAuth 2.0 (default): Required for browser-based clients like Claude. Requires hass-oidc-server to be installed and configured.
- Long-Lived Access Tokens (opt-in): For local agents and custom MCP clients that can’t run an OAuth browser flow. No extra dependencies. Must be enabled in the integration settings.
You can use both methods at the same time. When both are active, the server tries OAuth first and falls back to the Long-Lived Access Token.
Installation
HACS (Recommended)
- Open HACS in Home Assistant
- Search for “MCP Server”
- Click “Download”
- Restart Home Assistant
- Configure the integration (see Configuration section below)
Manual Installation
- Copy the
custom_components/mcp_server_http_transportfolder to your Home Assistantcustom_componentsdirectory - Restart Home Assistant
- Configure the integration (see Configuration section below)
Configuration
- Go to Settings > Devices & Services
- Click “Add Integration”
- Search for “MCP Server”
- Choose your authentication method:
- Leave “Enable native Home Assistant authentication” unchecked for OAuth-only (requires hass-oidc-server)
- Check it to allow Long-Lived Access Tokens (can be used alongside OAuth or on its own)
You can change this setting later via Settings > Devices & Services > MCP Server > Configure.
Usage with Claude in Browser (OAuth)
This requires the hass-oidc-server integration to be installed.
The MCP server uses OAuth 2.0 Dynamic Client Registration (DCR), which allows Claude to automatically register itself without manual client setup.
-
In Claude (claude.ai):
- Open Profile (bottom left corner)
- Click Settings (gear icon)
- Navigate to “Connectors”
- Click “Add custom connector”
- Enter your MCP server URL:
https://your-home-assistant.com/api/mcp - Click “Connect”
-
Claude will automatically:
- Discover your Home Assistant’s OAuth endpoints
- Register itself as an OAuth client
- Redirect you to Home Assistant for authentication
- Request access to your Home Assistant data
-
In Home Assistant:
- Log in if not already authenticated
- Review the permissions requested by Claude
- Click “Authorize” to grant access
That’s it! Claude will now be able to interact with your Home Assistant instance through the MCP server.
Usage with Long-Lived Access Tokens
For local agents or MCP clients that can’t run an OAuth browser flow, you can authenticate with a Home Assistant Long-Lived Access Token. This must be enabled first.
- Enable native authentication: Settings > Devices & Services > MCP Server > Configure > check “Enable native Home Assistant authentication”
- Create a token: go to your Home Assistant user profile > Long-Lived Access Tokens > Create Token
- Configure your MCP client to send the token as a Bearer header to
http://your-home-assistant:8123/api/mcp
MCP Capabilities
Tools
Entities & State
| Tool | Description |
|---|---|
get_state |
Get the current state of any entity (optional fields to limit attributes) |
batch_get_state |
Get state for multiple entities in one call (max 50) |
list_entities |
List all entities, with optional domain, detailed, and fields parameters |
search_entities |
Search entities by friendly name, device class, domain, or area |
get_device_details |
Get a device and every entity registered to it (all domains), with optional states |
call_service |
Call any Home Assistant service |
create_calendar_event |
Create a one-off calendar event (local calendars; entity API) |
create_recurring_calendar_event |
Create a recurring calendar series with RRULE (local calendars) |
list_calendar_events |
List events in a time window (uid for deletes; descriptions omitted by default) |
delete_calendar_events |
Delete events by uid or summary filter (supports dry_run preview) |
fire_event |
Fire a custom event on the Home Assistant event bus |
get_history |
Get state history of an entity over a time range |
get_logbook |
Fetch logbook entries for an entity or time range |
get_statistics |
Fetch long-term statistics (energy, climate) with configurable period |
list_statistic_ids |
List statistic IDs and their metadata (source, unit, whether they carry a mean/sum) |
validate_statistics |
Report statistics issues the recorder detected — the Developer Tools “Fix issues” list |
adjust_statistics |
Correct a statistic’s sum from a point in time onward (spike/bad reset); sum statistics only |
clear_statistics |
Permanently delete a statistic’s history so it can start clean (irreversible; requires confirm=true) |
render_template |
Evaluate a Jinja2 template |
Automations, Scenes & Scripts
| Tool | Description |
|---|---|
list_automations |
List all automations with full configuration |
get_automation_config |
Get full configuration of a single automation |
create_automation |
Create a new automation |
update_automation |
Update an existing automation |
delete_automation |
Delete an automation |
list_scenes |
List all scenes with full configuration |
get_scene_config |
Get full configuration of a single scene |
create_scene |
Create a new scene |
update_scene |
Update an existing scene |
delete_scene |
Delete a scene |
list_scripts |
List all scripts with full configuration |
get_script_config |
Get full configuration of a single script |
create_script |
Create a new script |
update_script |
Update an existing script |
delete_script |
Delete a script |
list_traces |
List recent execution traces for an automation/script (or a whole domain), newest first |
get_trace |
Get the full step-by-step execution trace of one run — which trigger fired, which conditions passed/failed, and the variables at each step (summary=true for an outline of large traces) |
Helpers
| Tool | Description |
|---|---|
list_helpers |
List all helper entities, optionally filtered by domain |
get_helper_config |
Get the raw stored configuration of a UI-managed helper (experimental) |
create_helper |
Create a new helper (input_boolean, input_number, input_text, input_select, input_datetime, input_button, counter, timer, schedule) (experimental) |
update_helper |
Update an existing UI-managed helper by entity ID (experimental) |
delete_helper |
Delete a UI-managed helper by entity ID (experimental) |
Config Files
| Tool | Description |
|---|---|
list_config_files |
List YAML files in the config directory (first level by default, recursive=true for split configs; secrets excluded) |
get_config_file |
Read the contents of a YAML config file (max 1 MB) |
save_config_file |
Write or replace a YAML config file; auto-backs up all files first, then validates config |
delete_config_file |
Delete a YAML config file; auto-backs up all files first |
batch_edit_config_files |
Write and/or delete multiple YAML files in one call; one backup and one config check for the whole batch |
backup_config_files |
Manually snapshot all YAML files into mcp_backups// |
list_config_backups |
List all available backup snapshots, newest first |
restore_config_backup |
Restore files from the latest or a specific backup; creates a pre-restore snapshot of the current state and runs config validation after restoring |
cleanup_config_backups |
Delete backup snapshots older than N days (default 30); keeps the folder from growing indefinitely |
Dashboards
| Tool | Description |
|---|---|
list_dashboards |
List all Lovelace dashboards with metadata |
get_dashboard_config |
Get a dashboard configuration; summary=true returns an outline of views and cards, path returns just the part a JSON Pointer addresses |
patch_dashboard_config |
Apply JSON Patch operations to a dashboard: move, add, remove, or edit individual cards without resending the whole config |
save_dashboard_config |
Save (replace) full dashboard configuration |
delete_dashboard_config |
Reset a dashboard configuration to empty |
create_dashboard |
Create a new Lovelace dashboard (experimental) |
update_dashboard |
Update dashboard metadata (experimental) |
delete_dashboard |
Delete a dashboard and its config (experimental) |
System & Infrastructure
| Tool | Description |
|---|---|
get_config |
Get Home Assistant configuration (version, location, units, timezone) |
get_system_status |
System overview: version, domain counts, entity totals, problem entities |
get_domain_stats |
Aggregate stats for a single domain (count, state breakdown, examples) |
check_config |
Validate Home Assistant configuration without restarting |
restart_ha |
Restart Home Assistant (requires explicit confirmation) |
get_error_log |
Fetch the Home Assistant error log (last N lines) |
list_areas |
List all areas |
list_devices |
List devices, optionally filtered by area |
list_services |
List available services, optionally filtered by domain |
describe_service |
Get a service’s full parameter schema: fields, selectors, examples, and targets |
list_integrations |
List installed integrations and their status |
list_labels |
List all labels for cross-domain grouping |
KNX
| Tool | Description |
|---|---|
knx_recent_telegrams |
Read Home Assistant’s KNX group-monitor telegram history — recent bus telegrams incl. source device and decoded value; regex-filter by group address / name, with a result limit. Retrospective (reads the stored buffer), ideal for finding which KNX device wrote a given group address |
knx_get_base_data |
KNX connection + project info: bus connection status, gateway address, xknx version, loaded ETS project metadata, and UI-creatable platforms |
knx_get_entities |
List KNX group addresses and the entities bound to each (the KNX-specific group-address↔entity binding view); optional regex filter on the group address |
knx_create_entity |
Create a KNX entity in the KNX UI config (config_store) from platform + data (experimental) |
knx_update_entity |
Update a UI-managed KNX entity by entity_id (experimental) |
knx_delete_entity |
Delete a UI-managed KNX entity by entity_id (experimental) |
Camera & Images
These tools are disabled by default; enable them per capability via Settings → Devices & Services → MCP Server → Configure. They return images directly to the model for visual analysis.
| Tool | Description |
|---|---|
get_camera_image |
Capture the current frame from a camera entity (optional width/height to downscale); no snapshot file is written (requires “Enable camera image access”) |
get_image_file |
Read an image file (JPEG, PNG, GIF, WebP) from an allowed directory, e.g. a snapshot saved by camera.snapshot (requires “Enable image file access”) |
Resources
| URI | Description |
|---|---|
hass://config |
Home Assistant configuration |
hass://areas |
All areas |
hass://devices |
All registered devices |
hass://services |
All available services by domain |
hass://floors |
All configured floors |
hass://entities |
All entities organized by domain |
hass://labels |
All labels |
hass://integrations |
Installed integrations with status |
hass://entity/{entity_id} |
State and attributes of a specific entity |
hass://dashboard/{url_path} |
Full configuration of a specific dashboard |
hass://entities/domain/{domain} |
Entities filtered by a specific domain |
Prompts
| Prompt | Description |
|---|---|
troubleshoot_device |
Diagnose issues with a specific entity |
daily_summary |
Summarize recent activity across all entities |
automation_review |
Review an automation’s config for issues and improvements |
energy_report |
Summarize energy consumption data over a time range |
setup_guide |
Guided troubleshooting for an entity in a problem state |
automation_builder |
Step-by-step guided automation creation |
automation_debugger |
Debug why an automation is not firing or misbehaving |
automation_audit |
Audit all automations for conflicts, redundancies, and anti-patterns |
schedule_optimizer |
Analyze automation schedules and suggest timing improvements |
naming_conventions |
Scan entity names for inconsistencies and suggest standardization |
dashboard_builder |
Suggest a Lovelace dashboard layout for given entities or area |
change_validator |
Pre-flight check after creating or modifying configurations |
security_review |
Scan for security issues in entities, integrations, and configuration |
Completions
Autocompletion is supported for entity_id, entity_ids, domain, service, area_id, url_path, automation_id, scene_id, script key, trigger_type, period, config_type, and helper domain arguments.
FAQ
License
MIT
インストール
This server does not publish a one-line install command.
Open the repository installation guide