Claude Desktop

The desktop Claude app supports espctl through one global config file.

Configuration

Edit (or create) the file at:

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.

Check it’s working

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.

If you see “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 server.

Claude Desktop-specific notes

• Claude Desktop is a single-config tool — there’s no per-project override. If you work on multiple ESP-IDF projects with different chips, the simplest pattern is to point cwd at a “current project” symlink that you flip between projects. Or use Claude Code instead, which has per-project settings.
• Environment variables you set in your shell (~/.zshrc, ~/.bashrc) are not inherited by GUI apps on macOS. Always list every variable directly inside the env block.

Tip

Ask Claude:

Read the install://claude-desktop resource.

…to get a copy-paste config pre-filled for your machine.