How to Use the ESPHome MCP in Windsurf

Q: How do I add this ESPHome MCP Server to Windsurf?

Open your /.codeium/windsurf/mcpconfig.json file and add the server config under the mcpServers key. Once saved, click the refresh button in your Windsurf MCP panel, and Cascade will immediately discover all ten tools.

Q: Do I need to compile my YAML file again to use these tools?

No. As long as your ESPHome nodes have the native webserver component active in their YAML configurations, this integration communicates directly with their existing HTTP REST endpoints.

Let Windsurf autonomously chain ESPHome actions to adjust your lights, covers, and fans based on live room telemetry.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect ESPHome MCP to Windsurf

Create your Vinkius account to connect ESPHome to Windsurf and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup ESPHome with Windsurf

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Multi-step smart home automation with Windsurf

Look, you don't want to manually trigger every single light switch when you are debugging. Windsurf uses Cascade to inspect your local setup directly, querying `get_entity_state` to see what is currently running, then deciding on its own to fire off a `switch_action` or a `light_action` to match your target state. You just tell the agent to prep the room, and it handles the sequence. Cascade handles the back-and-forth communication without nagging you. If a command fails, the agent checks the logs, adjusts the target values using `number_set` or `select_option`, and retries until the physical ESP32 device actually responds.

Autonomous diagnostics using the ESPHome MCP Server

Cascade keeps an eye on your physical microcontroller health while you write code. By invoking `get_metrics`, this MCP Server feeds raw Prometheus data directly into your Windsurf editor, letting the agent spot memory leaks or Wi-Fi drops before your ESPHome nodes crash. If a sensor goes offline, Cascade runs diagnostics on the fly. It reads the current configuration, checks the port, and attempts a `button_press` to reset the target controller or cycles a power relay via `switch_action` to bring the hardware back online.

Automated physical environment staging

Cascade prepares your physical workspace the second you start coding in Windsurf. When you open a specific workspace file, the agent triggers `cover_action` to lower your window blinds and runs `fan_action` to adjust the room temperature to your exact preference. If the ambient brightness drops while you are in a deep coding session, Cascade notices the change via `get_entity_state` and executes a `light_action` to brighten your desk lamp. You never have to leave your editor or grab your phone to change your room settings.

Setup guide

Set up ESPHome MCP in Windsurf

Prerequisites

Windsurf IDE installed (macOS, Windows, or Linux)
Active Vinkius subscription with a valid endpoint token

1

Open MCP configuration

Click the Cascade assistant icon in the sidebar, then click the hammer icon (🔨) at the top of the panel. Select "Configure" to open ~/.codeium/windsurf/mcp_config.json.
2

Add the ESPHome MCP

Paste the JSON snippet shown on the right into the mcpServers object. Replace [YOUR_TOKEN_HERE] with your endpoint token from cloud.vinkius.com.
3

Refresh MCPs

Go back to the hammer icon (🔨) in Cascade and click "Refresh". Windsurf will detect the new server. No full restart is needed — the connection is hot-reloaded.
4

Verify in Cascade

Start a new Cascade conversation and ask something like "Show my ESPHome payment history." If connected, Cascade will call the ESPHome tools directly. You will see a green dot next to the server name in the MCP panel.

mcp_config.json

{
  "mcpServers": {
    "esphome-mcp": {
      "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    }
  }
}

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by ESPHome. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect ESPHome now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about ESPHome MCP in Windsurf

Open your `~/.codeium/windsurf/mcp_config.json` file and add the server config under the `mcpServers` key. Once saved, click the refresh button in your Windsurf MCP panel, and Cascade will immediately discover all ten tools.

Yes. Because Cascade chains actions autonomously, you can tell it to shut down your entire office, and it will loop through `switch_action` and `cover_action` across multiple node IP addresses in a single execution thread.

Cascade reads the error returned by the Web Server API, checks the device status using `get_entity_state`, and automatically tries an alternative path, like adjusting a `number_set` value or retrying the command.

No. As long as your ESPHome nodes have the native web_server component active in their YAML configurations, this integration communicates directly with their existing HTTP REST endpoints.

No. Your raw ESPHome entity states and Prometheus metrics stay strictly on your local network. Windsurf talks directly to your local ESP32 IP addresses, meaning your physical device data never passes through external cloud relays.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript