How to add Hass-MCP to Windsurf

Control and query Home Assistant from Claude and other LLMs over the Model Context Protocol. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 304★ · stdio · apikey

Windsurf config for Hass-MCP

docker pull voska/hass-mcp:latest

{
  "mcpServers": {
    "hass-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HA_URL",
        "-e",
        "HA_TOKEN",
        "voska/hass-mcp"
      ],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
      }
    }
  }
}

Requires Docker to be installed and running.

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Hass-MCP config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Hass-MCP's tools become available to Cascade.

Before you start

A Home Assistant instance with a Long-Lived Access Token
Docker (recommended) OR Python 3.13+ with uv/uvx
An MCP client such as Claude Desktop, Cursor, or Claude Code CLI

What Hass-MCP can do in Windsurf

get_version

Get the Home Assistant version.

get_entity

Get the state of a specific entity, with optional field filtering.

entity_action

Perform actions on entities (turn on, off, toggle).

list_entities

Get a list of entities with optional domain filtering and search.

search_entities_tool

Search for entities matching a query.

domain_summary_tool

Get a summary of a domain's entities.

list_automations

Get a list of all automations.

call_service_tool

Call any Home Assistant service.

Security

Requires a Home Assistant Long-Lived Access Token (HA_TOKEN), which grants full control over the configured Home Assistant instance — store it securely. The optional HTTP transport exposes full Home Assistant control to anyone who can reach the port; it ships no built-in auth, so it must be placed behind a reverse proxy with auth, a VPN/zero-trust network, or bound to localhost only. The server binds 127.0.0.1 by default; never expose port 8000 to the open internet without auth. TLS verification cannot be disabled; for private CAs, install the CA root or set SSL_CERT_FILE.

Hass-MCP + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Hass-MCP config there under the "mcpServers" key and restart the client.

Is Hass-MCP safe to use with Windsurf?

How do I authenticate the server with Home Assistant?

Provide a Home Assistant Long-Lived Access Token via the HA_TOKEN environment variable, along with HA_URL pointing at your instance. Generate the token from your Home Assistant user profile.

Can I run it without Docker?

Yes. With Python 3.13+ and uv installed, you can run it via uvx by setting the command to 'uvx' with args ['hass-mcp'] and the same HA_URL / HA_TOKEN env vars.

What is the HTTP transport for, and is it safe to expose?

The streamable HTTP transport is for deployments that can't use stdio (MCP gateways, Smithery/PaaS hosting, or shared/network clients like LibreChat or OpenWebUI). It exposes full Home Assistant control with no built-in auth, so you must put it behind a reverse proxy with auth, a VPN/zero-trust network, or bind it to localhost only. Never expose port 8000 to the open internet without auth.

View repo Full Hass-MCP page