Claude Desktop
Why this agent
Claude Desktop is Anthropic’s GUI client for Claude. When espctl is wired in, any Claude Desktop chat can drive firmware builds — useful for users who prefer a chat-window UX over a terminal CLI.
Prerequisites
- Claude Desktop installed (macOS, Windows, or Linux).
espctlinstalled somewhere stable on disk (full path needed below).- (Optional, for remote builds) An Aegis build server URL +
MCP_AUTH_SECRET.
Install snippet (or alternative)
The desktop Claude app supports espctl through one global config file. Edit (or create) the file at:
| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json |
Merge the espctl entry into the mcpServers map (create it if it
doesn’t exist):
{
"mcpServers": {
"espctl": {
"command": "/path/to/espctl",
"args": ["mcp", "serve"],
"cwd": "/path/to/your/esp-idf/project",
"env": {
"CONTROL_BASE_URL": "https://esphome.cloud",
"MCP_AUTH_SECRET": "your-access-key"
}
}
}
}
Replace each /path/to/... with full paths on your computer. See
Claude Code for the field-by-field guide — the
meanings are the same.
Alternative — fetch a pre-filled snippet:
Read the
install://claude-desktopresource.
First-run verification
Quit Claude Desktop fully (Cmd+Q on macOS — not just close-window) and reopen it so the new config loads. Then in any chat:
List the espctl tools.
Expected: ~40 tools listed.
Troubleshooting
- “no tools” or “espctl failed to start” → click the small puzzle/plug icon in the message composer; Claude Desktop shows live status and the last error from each MCP server. Common cause: a shell-set env var the GUI app doesn’t inherit.
- Shell-set env vars not visible → environment variables you set
in your shell (
~/.zshrc,~/.bashrc) are not inherited by GUI apps on macOS. Always list every variable directly inside theenvblock. - No per-project override → Claude Desktop is a single-config tool.
If you work on multiple ESP-IDF projects with different chips, the
simplest pattern is to point
cwdat a “current project” symlink that you flip between projects. Or use Claude Code instead, which has per-project settings.