Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Claude Code

Claude Code 是 Anthropic 的 Claude 官方 CLI。把 espctl 接好之后,你就能在终端里用 日常中文让 Claude Code 帮你构建固件、看构建过程、读结果 —— 全在 对话框里。

配置

在 .claude/settings.json 的 mcpServers 下加一个 espctl 条目。 可以用项目级文件(<项目>/.claude/settings.json,跟着仓库走),也 可以用全局文件(~/.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"
      }
    }
  }
}

替换:

  • /path/to/espctl —— 你电脑上 espctl 程序的完整路径。
  • /path/to/your/esp-idf/project —— Claude 应该操作的项目的完整路径。
  • CONTROL_BASE_URL —— 你的构建服务器地址。把它(和 MCP_AUTH_SECRET) 留空就是仅计划模式。
  • MCP_AUTH_SECRET —— 构建服务器给你的访问密钥。当密码看;别放进 公开仓库。如果你把 .claude/settings.json check 进版本控制,先删掉 MCP_AUTH_SECRET 那一行,或者把这个文件加到 .gitignore。

看看是不是工作了

重启 Claude Code(/exit 然后再开)。然后问:

你有哪些 espctl 工具?

Claude 应该列出大约 40 件 —— build、doctor、store_versions、 project.init 等等。如果它说“没有工具“或“espctl 启动失败“:

  1. 自己在终端里跑一下 espctl mcp serve —— 它打印了什么错?
  2. 看 Claude Code 日志(macOS 上通常在 ~/Library/Logs/Claude)。
  3. 见故障排查。

项目级 vs 全局配置

位置适合
<项目>/.claude/settings.json大多数 ESP-IDF 项目。路径和芯片是项目特有的。把这个文件 check 进去(不要带访问密钥!),协作者就能拿到一样的配置。
~/.claude/settings.json你只有一个 ESP-IDF 项目,或者想让 espctl 默认在所有地方都可用。

常见模式:全局文件里放 espctl 路径和 CONTROL_BASE_URL,在每个 项目里只覆盖 cwd。

接下来问 Claude 什么

  • “运行 doctor” —— 快速健康检查。
  • “在这里初始化一个 esp32s3 项目” —— 新建项目。
  • “帮我构建成 esp32s3 固件,有错告诉我” —— 构建并汇报。

更长的示例见典型工作流。

提示:即拿即用的配置

espctl 自己能给你一份预填好你机器路径的代码片段。只要它接通了 (哪怕最小化地),就可以问:

读取 install://claude-code 资源,把 JSON 给我。