MCP Console (esphome.cloud/mcp/esp-idf)

The full espctl MCP tool set, running in a browser. Any AI agent that can control a Chromium browser gets the same 40 tools as espctl mcp serve — without installing anything.

Open esphome.cloud/mcp/esp-idf in Chrome or Edge. That’s it. No binary to download, no package to install, no PATH to configure. The agent clicks the UI, calls the tools, reads the results.

Not to be confused with the wizard at esphome.cloud/app, which is a guided step-by-step flow for humans. See Browser Wizard.

Who this is for

• AI agents with browser control (browser-use, computer-use, MCP-over-browser) — the primary audience. The agent opens Chrome, navigates to the URL, and has full MCP access with zero install.
• Developers who want to call MCP tools manually from a browser before wiring them into Claude Code or Cursor.
• Anyone without espctl installed — nothing to download, just open the URL.

Why this matters

If your AI agent can open a browser tab but can’t install binaries, this is the way in.

How an agent uses it

The full build-and-flash flow in 8 steps:

1. Open Chrome to esphome.cloud/mcp/esp-idf
2. Sign in (if prompted)
3. Click Connect                          → green dot appears
4. Pick target chip, IDF version, build type
5. Click Build                            → logs scroll live
6. Wait for build to succeed
7. Click Size Report / SBOM / Diagnostics → read results
8. Click download icon on firmware card   → .bin file ready

Optionally continue to flash:

9.  Switch to Flash tab
10. Click Connect → pick USB device
11. Click Flash                           → firmware written
12. Switch to Monitor tab → Open Monitor  → see device output

Each step is a click or a read. An AI agent with browser control follows exactly this sequence. A human can do the same — the UI is the same either way.

For client setup instructions (how to configure your AI agent to use the browser MCP), see Browser-Use Agent.

What it looks like

One page, three tabs, plus a tool list on the side:

Build tab

Connect

Sign in first — if you haven’t, you’ll see a sign-in prompt instead of the console. Once signed in, click Connect. The console opens the same three channels (espctl, pty, firmware) the wizard uses. A green dot means you’re connected.

Configure and build

1. Pick a target chip (esp32, esp32s3, esp32c3, …).
2. Optionally pick an IDF version (defaults to the build server’s default).
3. Pick release or debug.
4. Click Build.

Logs scroll live below the controls. Errors show red, warnings yellow.

After the build

Three extra actions appear when the build succeeds:

Download firmware

The Firmware Builds card lists finished builds. Click the download icon to pull the .bin file. It shows up in the Flash tab automatically.

Security note: Firmware may contain secrets (Wi-Fi passwords, API keys). Don’t share .bin files publicly. The build machine computes a SHA-256 hash and the console verifies it after download.

Flash tab

Plug in an ESP device over USB and flash it from the browser.

1. Click Connect to open a serial port.
2. Pick your device from the browser’s port list.
3. The last downloaded firmware is already selected.
4. Click Flash.

Browser requirement: Needs Chrome, Edge, or another Chromium-based browser. Safari and Firefox don’t support Web Serial.

Monitor tab

Works without connecting to the build server. No sign-in needed — just open the page, click the Monitor tab, and go.

A serial terminal that talks directly to your device over USB using the browser’s Web Serial API. Good for quick checks after flashing — boot messages, sensor readings, debug prints.

1. Click Open Monitor.
2. Pick your device from the browser’s port list.
3. Pick a baud rate (115200 is the ESP-IDF default).
4. Read the output. Type commands if your firmware accepts them.

Not a full terminal — no line editing or scroll-back.

Browser requirement — Chrome, Edge, or another Chromium browser. Safari and Firefox don’t support Web Serial.

Architecture

┌─────────────────────────────────────┐
│   Browser (MCP Console)             │
│  - Signs in                         │
│  - Opens a direct connection        │
│  - Sends tool calls over espctl     │
│  - Gets live logs over pty          │
│  - Downloads firmware over firmware │
└──────┬──────────────────────────────┘
       │ HTTPS (sign-in + setup)
       ▼
┌─────────────────────────────────────┐
│  Build server (esphome.cloud)       │
│  - Issues a short-lived permission  │
│  - Picks the best build machine     │
│  - Helps both sides find each other │
└──────┬──────────────────────────────┘
       │ Job assignment
       ▼
┌─────────────────────────────────────┐
│  Build machine                      │
│  - Checks the permission            │
│  - Talks directly to your browser   │
│  - Runs the build in a sandbox      │
│  - Sends back logs + firmware       │
└─────────────────────────────────────┘

Same connection as the wizard — same three channels, same setup through the build server, same sandbox. The difference is on the browser side: the console exposes the tools directly instead of wrapping them in a guided flow.

An AI agent with browser control drives this the same way a human would — click, read, click — but faster and without mistakes.

Exception: The Monitor tab skips all of this. It uses Web Serial to talk to your local device directly — no build server, no channels, no sign-in.

Security

Same rules as the Browser Wizard:

• Sign-in required. You must sign in before you can connect.
• Permissions last seconds, not minutes. If yours expires, disconnect and reconnect.
• Only three channels allowed. The permission says which channels (espctl, pty, firmware) you can open. The build machine rejects anything else.
• Bandwidth and rate limits. Each permission has caps per channel. The build machine enforces them.
• Encrypted end-to-end. The build server can’t read your traffic.
• Certificate check. The build machine checks that your certificate matches the one in the permission. A stolen permission won’t work for someone else.

Full details in Grants & Security.

Console vs wizard vs local MCP

See also

• Browser Wizard — the guided version for humans.
• Typical 8-Step Workflow — same flow, driven by an AI.
• System Overview — bigger picture.
• WebRTC & Data Channels — how the build machine enforces permissions.
• Tool Reference — all 40 tools.