How to Use the ESPHome MCP in Claude Code

Q: How do I install the ESPHome MCP Server in Claude Code?

Run claude mcp add --transport http esphome-mcp -- in your terminal. This command registers the server in your /.claude.json configuration file, making all ten tools instantly available.

Control and monitor your ESPHome microcontrollers directly from your terminal using Claude Code shell commands.

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 Claude Code

Create your Vinkius account to connect ESPHome to Claude Code 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 Claude Code

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Headless terminal control for ESPHome via Claude Code

Claude Code lets you manage your physical hardware without opening a browser or an IDE. From a single terminal prompt, you can instruct the agent to query `get_entity_state` or trigger a `switch_action` across your entire network of ESP32 devices. Because it runs directly in your shell, you can pipe the output of this MCP Server into standard command-line utilities. You can grep the results of `get_metrics` to quickly identify offline nodes or format the output into clean terminal tables.

Automated terminal diagnostics with this MCP Server

Claude Code can run scheduled terminal tasks to audit your smart home hardware. You can write a shell loop that asks the agent to check `get_metrics` every hour, parsing the Prometheus data to track Wi-Fi signal strength across all nodes. If a node shows high latency, the agent can automatically trigger a `button_press` to reboot the device or use `select_option` to switch it to a backup access point, keeping your local network stable.

Direct physical operations from your shell

You can execute rapid physical changes right from your terminal prompt. Tell the CLI agent to prepare your server rack, and it will trigger `fan_action` to increase cooling and `cover_action` to open the cabinet vents. If an emergency occurs, a single command lets Claude Code trigger `alarm_action` or cut power to a faulty bench supply using `switch_action`. It gives your terminal direct, low-latency control over physical relays.

Setup guide

Set up ESPHome MCP in Claude Code

Prerequisites

Claude Code CLI installed (npm install -g @anthropic-ai/claude-code)
Active Vinkius subscription with a valid endpoint token

1

Run the add command

Open your terminal and run the command shown on the right. Replace [YOUR_TOKEN_HERE] with your endpoint token from cloud.vinkius.com. Use --scope user to make it available across all projects.
2

Verify the connection

Start a Claude Code session and type /mcp to list connected servers. You should see esphome-mcp with a green status indicator.
3

Start using tools

Ask Claude Code something like "Check my latest ESPHome transactions." It will automatically discover and invoke the available ESPHome tools.

Terminal

claude mcp add --transport http esphome-mcp https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp

Get your connection token →

Prerequisites

Claude Code CLI installed
Active Vinkius subscription with a valid endpoint token

1

Open the config file

Create or edit .mcp.json in your project root for project-level scope, or ~/.claude.json for user-level scope.
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

Restart Claude Code

Start a new Claude Code session. Type /mcp to confirm the server is connected. The tools will be automatically available in your conversation.

.mcp.json

{
  "mcpServers": {
    "esphome-mcp": {
      "type": "url",
      "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 Claude Code

Run `claude mcp add --transport http esphome-mcp -- ` in your terminal. This command registers the server in your `~/.claude.json` configuration file, making all ten tools instantly available.

Yes. You can ask Claude Code to write a shell script that uses `light_action` and `switch_action` to shut down all office devices at the end of the day, running it directly from your terminal.

The CLI agent detects connection drops through HTTP status codes, automatically queries `get_entity_state` to verify node availability, and outputs clear terminal logs explaining the failure.

No. This integration bypasses Home Assistant entirely, using the native ESPHome Web Server REST API to talk directly to each individual microcontroller on your network.

Yes. All ESPHome API payloads, metric logs, and device states are kept strictly local. The terminal client communicates directly with your ESP32 IP addresses, ensuring no physical device data is exposed to external servers.

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