Claude Code

Claude Code is Anthropic’s official CLI for Claude. Once espctl is wired up, you can ask Claude Code in plain English to build firmware, watch the build, and read the result — all from your terminal.

Configuration

Add an espctl entry under mcpServers in .claude/settings.json. Use the per-project file (<project>/.claude/settings.json, kept in your repo) or the global file (~/.claude/settings.json).

{
  "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:

/path/to/espctl — full path to the espctl program on your computer.
/path/to/your/esp-idf/project — full path to the project Claude should work on.
CONTROL_BASE_URL — your build server URL. Leave it (and MCP_AUTH_SECRET) out to run in plan-only mode.
MCP_AUTH_SECRET — your access key from the build server. Treat it like a password; don’t put it in a public repo. If you check your .claude/settings.json into version control, remove the MCP_AUTH_SECRET line first or add the file to .gitignore.

Check it’s working

Restart Claude Code (/exit, then re-open). Then ask:

What espctl tools do you have?

Claude should list about 40 things — build, doctor, store_versions, project.init, and so on. If it says “no tools” or “espctl failed to start”:

Run espctl mcp serve in a terminal yourself — does it print an error?
Check Claude Code’s logs (usually ~/Library/Logs/Claude on macOS).
See Troubleshooting.

Per-project vs global config

Where	When to use
`<project>/.claude/settings.json`	Most ESP-IDF projects. The path and chip target are project-specific. Check the file in (without the access key!) so collaborators get the same setup.
`~/.claude/settings.json`	When you only have one ESP-IDF project, or you want espctl available everywhere by default.

A common pattern: keep the espctl path and CONTROL_BASE_URL in the global file, and just override cwd per project.

What to ask Claude next

“Run doctor” — quick health check.
“Initialize an esp32s3 project here” — sets up a new project.
“Build the project for esp32s3 and tell me if anything breaks” — builds and reports back.

See Typical Workflow for a longer example.

Tip: ready-to-paste config

espctl can hand you the snippet above pre-filled for your machine. Once it’s wired up at all (even minimally), ask:

Read the install://claude-code resource and show me the JSON.