Hass-MCP

MCP server for Home Assistant: an agent reads device states, controls them and edits smart home dashboards

Install

In your terminal, with SkillFoxx CLI

npx skillfoxx add mcp/hass-mcp

Detects the agents on your machine, checks the risk and pins the version.

Other ways to install

This entry is high risk, so there is no one-click install. Review the code and add the config by hand.

Run in a terminal

claude mcp add --transport stdio --env 'HA_URL=<HA_URL value>' --env 'HA_TOKEN=<your HA_TOKEN>' hass-mcp -- docker run -i --rm -e HA_URL -e HA_TOKEN voska/hass-mcp

Or add to the file .mcp.json, in the project

{
  "mcpServers": {
    "hass-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HA_URL",
        "-e",
        "HA_TOKEN",
        "voska/hass-mcp"
      ],
      "env": {
        "HA_URL": "<HA_URL value>",
        "HA_TOKEN": "<your HA_TOKEN>"
      }
    }
  }
}

If the file already exists, add the server inside the mcpServers key.

Keys and settings

HA_URLrequired
HA_TOKENsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Add to the file ~/.cursor/mcp.json, for all projects

{
  "mcpServers": {
    "hass-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HA_URL",
        "-e",
        "HA_TOKEN",
        "voska/hass-mcp"
      ],
      "env": {
        "HA_URL": "<HA_URL value>",
        "HA_TOKEN": "<your HA_TOKEN>"
      }
    }
  }
}

If the file already exists, add the server inside the mcpServers key. For a single project, put the same block into .cursor/mcp.json.

Keys and settings

HA_URLrequired
HA_TOKENsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Run in a terminal

code --add-mcp '{"name":"hass-mcp","type":"stdio","command":"docker","args":["run","-i","--rm","-e","HA_URL","-e","HA_TOKEN","voska/hass-mcp"],"env":{"HA_URL":"<HA_URL value>","HA_TOKEN":"<your HA_TOKEN>"}}'

Or add to the file .vscode/mcp.json, in the project

{
  "servers": {
    "hass-mcp": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HA_URL",
        "-e",
        "HA_TOKEN",
        "voska/hass-mcp"
      ],
      "env": {
        "HA_URL": "<HA_URL value>",
        "HA_TOKEN": "<your HA_TOKEN>"
      }
    }
  }
}

If the file already exists, add the server inside the servers key.

Keys and settings

HA_URLrequired
HA_TOKENsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Run in a terminal

codex mcp add hass-mcp --env 'HA_URL=<HA_URL value>' --env 'HA_TOKEN=<your HA_TOKEN>' -- docker run -i --rm -e HA_URL -e HA_TOKEN voska/hass-mcp

Or add to the file ~/.codex/config.toml, for all projects

[mcp_servers.hass-mcp]
command = "docker"
args = ["run", "-i", "--rm", "-e", "HA_URL", "-e", "HA_TOKEN", "voska/hass-mcp"]
env = { HA_URL = "<HA_URL value>", HA_TOKEN = "<your HA_TOKEN>" }

If the file already exists, append the block to the end.

Keys and settings

HA_URLrequired
HA_TOKENsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Add to the file ~/.gemini/settings.json, for all projects

{
  "mcpServers": {
    "hass-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HA_URL",
        "-e",
        "HA_TOKEN",
        "voska/hass-mcp"
      ],
      "env": {
        "HA_URL": "<HA_URL value>",
        "HA_TOKEN": "<your HA_TOKEN>"
      }
    }
  }
}

If the file already exists, add the server inside the mcpServers key.

Keys and settings

HA_URLrequired
HA_TOKENsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Add to the file ~/.config/devin/mcp_config.json, for all projects

{
  "mcpServers": {
    "hass-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HA_URL",
        "-e",
        "HA_TOKEN",
        "voska/hass-mcp"
      ],
      "env": {
        "HA_URL": "<HA_URL value>",
        "HA_TOKEN": "<your HA_TOKEN>"
      }
    }
  }
}

If the file already exists, add the server inside the mcpServers key. Legacy Cascade keeps the MCP config in ~/.codeium/windsurf/mcp_config.json.

Keys and settings

HA_URLrequired
HA_TOKENsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Formerly Windsurf.

Add to the file cline_mcp_settings.json, for all projects

{
  "mcpServers": {
    "hass-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HA_URL",
        "-e",
        "HA_TOKEN",
        "voska/hass-mcp"
      ],
      "env": {
        "HA_URL": "<HA_URL value>",
        "HA_TOKEN": "<your HA_TOKEN>"
      }
    }
  }
}

If the file already exists, add the server inside the mcpServers key. Open the settings file in Cline: MCP Servers tab, Configure MCP Servers.

Keys and settings

HA_URLrequired
HA_TOKENsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Add to the file .roo/mcp.json, in the project

{
  "mcpServers": {
    "hass-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HA_URL",
        "-e",
        "HA_TOKEN",
        "voska/hass-mcp"
      ],
      "env": {
        "HA_URL": "<HA_URL value>",
        "HA_TOKEN": "<your HA_TOKEN>"
      }
    }
  }
}

If the file already exists, add the server inside the mcpServers key.

Keys and settings

HA_URLrequired
HA_TOKENsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

A fork of Roo Code, same .roo folders.

Add to the file opencode.json, in the project

{
  "mcp": {
    "hass-mcp": {
      "type": "local",
      "command": [
        "docker",
        "run",
        "-i",
        "--rm",
        "-e",
        "HA_URL",
        "-e",
        "HA_TOKEN",
        "voska/hass-mcp"
      ],
      "environment": {
        "HA_URL": "<HA_URL value>",
        "HA_TOKEN": "<your HA_TOKEN>"
      }
    }
  }
}

If the file already exists, add the server inside the mcp key.

Keys and settings

HA_URLrequired
HA_TOKENsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Add to the file ~/.config/zed/settings.json, for all projects

{
  "context_servers": {
    "hass-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HA_URL",
        "-e",
        "HA_TOKEN",
        "voska/hass-mcp"
      ],
      "env": {
        "HA_URL": "<HA_URL value>",
        "HA_TOKEN": "<your HA_TOKEN>"
      }
    }
  }
}

If the file already exists, add the server inside the context_servers key.

Keys and settings

HA_URLrequired
HA_TOKENsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Add to the file .codeassistant/mcp.json, in the project

{
  "mcpServers": {
    "hass-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HA_URL",
        "-e",
        "HA_TOKEN",
        "voska/hass-mcp"
      ],
      "env": {
        "HA_URL": "<HA_URL value>",
        "HA_TOKEN": "<your HA_TOKEN>"
      }
    }
  }
}

If the file already exists, add the server inside the mcpServers key.

Keys and settings

HA_URLrequired
HA_TOKENsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

You will need: Docker

Checked against the repository on Sep 25, 2026, commit e05bfde.

Text for your agent

Add the hass-mcp server to your MCP client config: command uvx, args hass-mcp, and in env set HA_URL to your Home Assistant address and HA_TOKEN to a long-lived token. The voska/hass-mcp Docker image is an alternative.

Other ways from the author

uvx hass-mcp

Set HA_URL and HA_TOKEN in the environment before running. Requires Python 3.13 and uv.

This is third-party code. Review the repository files before installing.

What it does

The server links an agent to your Home Assistant instance. It reads device and sensor states, searches entities, turns lights and appliances on and off, calls any service and restarts Home Assistant. It offers entity history and long-term statistics, error log reading and live Lovelace dashboard editing over WebSocket with automatic backups. It ships with guided prompts for creating and debugging automations.

Who it is for. For Home Assistant smart home owners who want to control and configure it through an agent.

Good fit when

You want to ask about device and sensor states at home
You want to turn appliances on, off or toggle by voice or text
You want to review automations, history or Home Assistant dashboards

Not a fit when

You have no Home Assistant instance with a long-lived token
You cannot trust the client with full control over your home and devices

Example request

What is the bedroom temperature, and turn off the kitchen lights

Limitations

You need a Home Assistant instance with a long-lived token, and to edit Lovelace dashboards the token must belong to an admin and work only with UI storage-mode dashboards. It runs from the voska/hass-mcp Docker image or via uvx with the hass-mcp package; Python 3.13 and uv are required. The http mode exposes full home control over the network without built-in auth, so it must not face the internet without a reverse proxy or VPN.

How to disable. Remove the hass-mcp block from your MCP client config and restart it. If running in Docker, stop and remove the container, and revoke the long-lived token in Home Assistant if needed.

MCP

Transport: stdio, http
Authentication: API key

Environment variables
Environment variables
HA_URL required	URL of your Home Assistant instance
HA_TOKEN required, secret	Home Assistant long-lived access token
SSL_CERT_FILE	Path to your own CA root certificate

Security check

Controls real home devices, including lights, appliances and locks
Can restart Home Assistant and call any of its services
Edits dashboards and handles a long-lived access token

README in short

The README covers installation via the voska/hass-mcp Docker image and via uvx with the hass-mcp package, plus setup for Claude Desktop, Cursor and Claude Code with the HA_URL and HA_TOKEN variables. It lists tools for entity state and search, entity actions, service calls, restart, history and statistics, the error log and live Lovelace dashboard editing with backups. It separately shows the streamable http transport with a security warning and custom CA setup. It includes guided prompts and resources, licensed under MIT.

FAQ

Which token is needed?

A long-lived access token from your Home Assistant profile. To edit Lovelace dashboards the token must belong to an admin.

Is http mode safe?

It exposes full home control over the network without built-in auth. Put it behind a reverse proxy, a VPN or a localhost-only binding and do not face it to the internet.

n8n-MCP

Editors’ pick

An MCP server with n8n node and template knowledge: the agent picks nodes, validates configs and, with API access, creates workflows in your n8n

MCP serverHigh riskNo VPN needed23K

Zapier MCP

Official

Zapier's official MCP plugin: the agent gets actions across thousands of apps through your Zapier account

PluginHigh risk421

Awesome Claude Skills by Composio

Awesome Claude Skills

A curated list of Claude skills and plugins, plus Composio's own automation skills for 78 SaaS apps

SkillHigh risk75.8K

CLI-Anything

A plugin and CLI catalog for agents: generates command-line interfaces for GUI apps like GIMP and Blender and installs ready ones via CLI-Hub

PluginHigh riskNo VPN needed50.9K

Install

What it does

Good fit when

Not a fit when

Example request

Limitations

MCP

Security check

README in short

FAQ

Related

n8n-MCP

Zapier MCP

Awesome Claude Skills by Composio

CLI-Anything