ESPHome MCP Server

ESPHome MCP Server

A custom Model Context Protocol (MCP) server for managing ESPHome devices via the ESPHome Device Builder WebSocket & REST API.

It allows AI assistants (like Claude, Gemini, or custom agents) to inspect, edit, validate, compile, and flash ESPHome firmware Over-The-Air (OTA) directly from conversation context.

Features

• esphome_list_devices: Lists all registered ESPHome devices, IP addresses, online statuses, board architectures, and YAML filenames.
• esphome_get_config: Retrieves full YAML configuration for any device (e.g. esp32-shelf.yaml).
• esphome_update_config: Saves updated YAML configurations directly to the ESPHome instance.
• esphome_validate: Validates YAML syntax & component configurations before compilation.
• esphome_compile: Triggers C++ compilation of device firmware.
• esphome_flash_ota: Flashes compiled firmware Over-The-Air (OTA) over Wi-Fi.

How It Works

The server connects directly over local WebSockets to the standard ESPHome Device Builder dashboard (port 6052) running on your network.

• No Home Assistant Add-ons Required: It bypasses third-party container layers and talks directly to ESPHome.
• No SSH / Samba Mounts Needed: Configs are read, updated, validated, and flashed over the native ESPHome WebSocket API.

Quick Start (Automated Setup)

Run the automated installer script to create the virtual environment, install dependencies, verify your ESPHome connection, and automatically register the server with your MCP client:

git clone https://github.com/saihgupr/esphome-mcp.git
cd esphome-mcp
python3 install.py

The script will prompt for your ESPHome IP/Host & Port, test the connection, create the .venv, and automatically add esphome to your mcp_config.json (Antigravity IDE, Claude Desktop, Cursor, etc.).

Note: After running install.py, fully restart your IDE or AI Client application (Quit & Relaunch) to load the new MCP server.

Manual Configuration (Alternative)

If you prefer to configure manually, create .venv and update your MCP client configuration file (e.g. ~/.gemini/config/mcp_config.json or claude_desktop_config.json) using absolute paths:

{
  "mcpServers": {
    "esphome": {
      "command": "/Users/your-username/path/to/esphome-mcp/.venv/bin/python",
      "args": [
        "/Users/your-username/path/to/esphome-mcp/server.py"
      ],
      "env": {
        "ESPHOME_HOST": "192.168.1.4",
        "ESPHOME_PORT": "6052"
      },
      "disabled": false
    }
  }
}

Environment Variables

Usage & Examples

Once configured in your MCP client, you can manage your ESPHome devices using natural conversation.

Example Prompts:

• Check Device Status:

  "List all my ESPHome devices and show which ones are currently online."

• Inspect Configuration:

  "Show me the configuration file for esp32-shelf.yaml."

• Edit, Validate & OTA Update:

  "Update esp32-shelf.yaml so pressing the door button triggers a 180-degree LED hue shift for half a second. Validate the config, and if valid, flash the update OTA over Wi-Fi."

• Compile Test:

  "Check nodemcu-2.yaml for syntax errors and compile the binary to verify the build."

Contributing

Contributions are welcome! Please submit all Pull Requests to the develop branch.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/awesome-feature)
3. Commit your changes and push to your fork
4. Open a Pull Request to develop

Support & Feedback

If you encounter any issues, bugs, or have feature requests, please open an issue on GitHub.

ESPHome MCP Server is open-source and free. If you find it useful, consider giving it a star ⭐ or making a donation to support development!