ha-mcp — Claude Code MCP server: features and setup
ha-mcp connects an AI assistant to Home Assistant so it can control devices, check their states and call services. Use it to manage smart-home tasks through chat.
claude mcp add ha-mcp -- uvx ha-mcpWhat ha-mcp does
With ha-mcp, an assistant can interact with Home Assistant over MCP. Ask it to change a device state, retrieve current values, call a service or work with automations. The server also adds an admin-only HA-MCP panel to the Home Assistant sidebar.
For Claude Code, add the server with claude mcp add ha-mcp -- uvx ha-mcp. This setup uses uvx; the Home Assistant component setup instead requires an administrator token, with client access configured separately. Choose one way to run ha-mcp: running multiple installations at once can cause conflicts.
What it helps with
- control Home Assistant devices through an assistant
- check a device’s current state from chat
- call a Home Assistant service with a request
- manage automations through an AI assistant
Example prompts for the agent
- Turn off the living room light through Home Assistant.
- Show me the current temperature sensor readings.
- Call the Home Assistant service to restart the router.
How to install ha-mcp
Platform CLI
claude mcp add ha-mcp -- uvx ha-mcpuvx runs the command named after the package; if the README names another one, use uvx --from ha-mcp <command>
Platform CLI
codex mcp add ha-mcp -- uvx ha-mcpuvx runs the command named after the package; if the README names another one, use uvx --from ha-mcp <command>
Config file
{
"mcpServers": {
"ha-mcp": {
"command": "uvx",
"args": [
"ha-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from ha-mcp <command>
Config file
{
"servers": {
"ha-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"ha-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from ha-mcp <command>
Platform CLI
gemini mcp add ha-mcp uvx ha-mcpuvx runs the command named after the package; if the README names another one, use uvx --from ha-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about ha-mcp
How do I install ha-mcp in Claude Code?
Run claude mcp add ha-mcp -- uvx ha-mcp to add the MCP server under the name ha-mcp.
What does ha-mcp do?
It connects an AI assistant to Home Assistant to control devices, check states and call services. It can also work with automations.
Can I run more than one ha-mcp installation at a time?
The setup instructions recommend choosing one run method. Don’t run the Home Assistant component alongside another ha-mcp installation.
