mcp-hass — Claude Code skill: control Home Assistant over MCP
A skill that wires your agent to Home Assistant through MCP: read device states, flip lights and fans. Handy when you want to poke the smart home from chat.
npx skills add aahl/skills --skill mcp-hass -a claude-codeWhat mcp-hass does
The skill gives the agent access to your Home Assistant instance over MCP. It reads current states and switches devices — lights, fans, whole areas by name. Calls go through mcporter, a CLI for invoking MCP tools.
Before anything works, enable the MCP server inside Home Assistant: Settings > Devices & services, hit the add-integration button, pick Model Context Protocol from the list. You also need HASS_BASE_URL and HASS_ACCESS_TOKEN in the environment. If the agent reports the MCP server is missing, that usually means the config was never added — the skill then nudges you toward those two variables.
Config itself is one command: npx -y mcporter config add home-assistant, with http transport and a bearer header. No access token, no calls — Home Assistant will reject the request. To see every parameter each tool accepts, run npx -y mcporter list home-assistant --schema --all-parameters.
What it helps with
- turn on a room light without opening the Home Assistant app
- check what the sensors and devices report right now
- switch off every lamp in an area with one call
- set a light's brightness as a percentage
- set fan speed by name or area
Example prompts for the agent
- turn on the bedroom light
- what's the temperature in the living room right now?
- turn off all lights in the Bedroom area
How to install mcp-hass
1Skills CLI (Vercel)
npx skills add aahl/skills --skill mcp-hass -a claude-code2Manually: put the files in place
~/.claude/skills/mcp-hass/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/mcp-hass/
1Skills CLI (Vercel)
npx skills add aahl/skills --skill mcp-hass -a codex2Manually: put the files in place
.agents/skills/mcp-hass/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add aahl/skills --skill mcp-hass -a cursor2Manually: put the files in place
.cursor/skills/mcp-hass/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install aahl/skills mcp-hass2Manually: put the files in place
.github/skills/mcp-hass/SKILL.md1Skills CLI (Vercel)
npx skills add aahl/skills --skill mcp-hass -a gemini-cli2Platform CLI
gemini skills install https://github.com/aahl/skills --path skills/mcp-hassManually: put the files in place
.devin/skills/mcp-hass/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add aahl/skills --skill mcp-hass -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about mcp-hass
How do I install mcp-hass in Claude?
Run npx skills add aahl/skills --skill mcp-hass -a claude-code. The skill lands at ~/.claude/skills/mcp-hass/SKILL.md.
What does mcp-hass do?
It connects the agent to Home Assistant over MCP so it can query device states, turn lights on and off, and adjust brightness or fan speed.
What has to be set up before using the skill?
Enable the Model Context Protocol integration in Home Assistant, set HASS_BASE_URL and HASS_ACCESS_TOKEN, then add the config with npx -y mcporter config add home-assistant.
Source text
SKILL.md · MIT
---
name: mcp-hass
description: The skill for control Home Assistant smart home devices and query states using MCP protocol.
---
# Home Assistant
Control Home Assistant smart home and query states using MCP protocol.
## Prerequisites
Enable MCP server in Home Assistant:
- Browse to your Home Assistant instance.
- Go to Settings > Devices & services.
- In the bottom right corner, select the [+ Add Integration](https://my.home-assistant.io/redirect/config_flow_start?domain=mcp) button.
- From the list, select Model Context Protocol.
- Follow the instructions on screen to complete the setup.
## Config
When prompted that the MCP server does not exist, remind the user to configure the `HASS_BASE_URL` and `HASS_ACCESS_TOKEN` environment variables by executing the following command to add the configuration:
```shell
npx -y mcporter config add home-assistant \
--transport http \
--url "${HASS_BASE_URL:-http://homeassistant.local:8123}/api/mcp" \
--header "Authorization=Bearer \${HASS_ACCESS_TOKEN}"
```
## Usage
```shell
# Get states
npx -y mcporter call home-assistant.GetLiveContext
# Turn on the device
npx -y mcporter call home-assistant.HassTurnOn(name: "Bedroom Light")
npx -y mcporter call home-assistant.HassTurnOn(name: "Light", area: "Bedroom")
# Turn off the device
npx -y mcporter call home-assistant.HassTurnOff(name: "Bedroom Light")
npx -y mcporter call home-assistant.HassTurnOff(area: "Bedroom", domain: ["light"])
# Control light
# brightness: The percentage of the light, where 0 is off and 100 is fully lit.
# color: Name of color
npx -y mcporter call home-assistant.HassLightSet(name: "Bedroom Light", brightness: 50)
# Control fan
# percentage: The percentage of the fan, where 0 is off and 100 is full speed.
npx -y mcporter call home-assistant.HassFanSetSpeed(name: "Fan", area: "Bedroom", percentage: 80)
```
Execute the following command to learn about specific usage methods:
- `npx -y mcporter list home-assistant --schema --all-parameters`
## About `mcporter`
- To improve compatibility, use `npx -y mcporter` instead of `mcporter` when executing commands.
- https://github.com/steipete/mcporter/raw/refs/heads/main/docs/call-syntax.md
- https://github.com/steipete/mcporter/raw/refs/heads/main/docs/cli-reference.md
© aahl · MIT · aahl/skills
