# ESPHome MCP > ESPHome MCP connects any AI agent to your ESPHome microcontrollers, letting you manage and monitor physical IoT devices using natural conversation. Get real-time sensor readings or change the color of a light without opening a dashboard. It lets you control switches, set blinds, arm alarms, and more, all through simple chat commands. ## Overview - **Category:** loved-by-devs - **Price:** Free - **Tags:** esp32, esp8266, home-automation, smart-home, microcontrollers, sensors ## Description Managing smart home hardware usually means jumping between apps and complex dashboards. This MCP changes that. It connects your ESPHome-powered devices to any AI agent, giving your natural language prompts direct access to the physical world. You can ask your agent for the current temperature reading or tell it to change the living room light to a specific color. Need to automate something? Your agent handles complex routines—like turning off lights and setting the alarm after you leave. This capability is hosted on Vinkius, giving your AI client access to thousands of other hardware controllers, making it the central hub for all your smart devices. ## Tools ### alarm_action Triggers an action on an alarm control panel, such as arming or disarming the system. ### button_press Simulates a physical button press event on an entity. ### cover_action Controls motorized covers, including adjusting blinds or garage doors to specific positions. ### fan_action Changes the operational state of a fan entity (e.g., on/off or speed). ### get_entity_state Retrieves the current status, value, or reading from any specified sensor or switch. ### get_metrics Pulls detailed Prometheus performance metrics directly from the connected device. ### light_action Manages lights, allowing you to turn them on or off and set specific color values (RGB). ### number_set Sets a precise numeric value for an entity that accepts continuous data. ### select_option Forces an entity to adopt one specific option from a predefined list of choices. ### switch_action Toggles the power state (on/off) for a standard electrical switch. ## Prompt Examples **Prompt:** ``` What is the current reading of the 'living_room_temperature' sensor? ``` **Response:** ``` Checking the sensor... The current state of 'living_room_temperature' is 22.5°C. ``` **Prompt:** ``` Turn on the kitchen light and set it to a warm orange color. ``` **Response:** ``` I've sent the command to the kitchen light. It is now on with the RGB values set to (255, 165, 0). ``` **Prompt:** ``` Close the garage door cover. ``` **Response:** ``` Executing the close action on the garage door cover. The command has been sent successfully. ``` ## Capabilities ### Monitor sensor data Retrieve the current status and value from any connected sensor or digital switch. ### Control lighting systems Adjust lights by turning them on, off, or setting precise colors and brightness levels. ### Manage mechanical components Operate blinds, garage doors, fans, and standard switches using conversational commands. ### Handle security protocols Arm or disarm alarm panels directly from your chat interface. ### Set numerical states Adjust specific values on devices, like temperature set points or dimmer levels. ## Use Cases ### The 'Leaving Home' routine A homeowner asks their agent, 'I'm leaving.' The agent triggers the sequence: it uses `light_action` to turn off all non-essential lights, executes `cover_action` to close the garage door, and finally calls `alarm_action` to arm the system. All done with one command. ### Troubleshooting a sensor reading A developer asks their agent about a temperature fluctuation. The agent immediately uses `get_entity_state` to pull the live data, and then runs `get_metrics` to check if the device itself is reporting unusual performance metrics. ### Setting a complex scene An engineer needs to set up a climate control test. They ask the agent to 'Set the target temperature to 24 degrees and ensure the fan is running.' The MCP uses `number_set` for the temperature and `fan_action` to activate the cooling. ### Remote access testing A hardware team member needs to test a prototype blind. They simply tell their agent, 'Close the main blinds.' The MCP executes the action using `cover_action`, allowing them to verify functionality without needing local physical access. ## Benefits - Stop clicking through menus. You can now monitor any sensor reading or change a light's color just by asking your agent, which uses the `get_entity_state` and `light_action` tools. - Run complex routines like 'movie night' in one go. Your agent coordinates multiple actions, such as setting a specific number using `number_set`, dimming lights with `light_action`, and closing blinds via `cover_action`. - Get performance data without logs. Need to check the device health? The `get_metrics` tool pulls Prometheus data directly into your conversation context for immediate debugging. - Simplify security management. Use `alarm_action` to arm or disarm panels, eliminating the need to physically interact with a separate key switch just to run an automation script. - Handle all inputs: From simple on/off toggles using `switch_action` to pressing virtual buttons via `button_press`, this MCP covers every common interaction point. ## How It Works The bottom line is that your physical hardware speaks directly to your AI client over a simple API connection. 1. First, enable the `web_server` component in your ESPHome YAML configuration file. 2. Next, subscribe to this MCP and provide your device's local URL and any required password within Vinkius. 3. Finally, tell your AI agent to perform an action, like 'Set the kitchen light to blue,' and it handles the rest. ## Frequently Asked Questions **How does the ESPHome MCP handle multiple devices?** The MCP uses entity IDs to manage every single device, whether it is a light or a fan. You simply reference the specific ID when you ask your agent for an action. **Can I use the ESPHome MCP to read sensor data?** Yes. Use `get_entity_state` to pull real-time readings from any connected temperature, humidity, or binary sensor. **Is the ESPHome MCP only for simple on/off actions?** No. You can do far more. For example, you can use `light_action` to set specific RGB colors, not just turn them on or off. **What if I need to check the device health metrics with ESPHome MCP?** You call the `get_metrics` tool. This fetches detailed performance data from your device using Prometheus standards for advanced debugging. **How do I make the blinds move using the ESPHome MCP?** Use the `cover_action`. You can tell your agent to 'Close the garage door' or specify a position and tilt angle within that command.