Claude Code

Why this agent

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

Prerequisites

已安装 Claude Code 并在 $PATH 中。
espctl 已安装在磁盘上某个稳定位置(下文需要完整路径)。
(可选,用于远程构建)Aegis 构建服务器地址 + MCP_AUTH_SECRET 访问密钥。

Install snippet (or alternative)

在 .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。

或者 —— 让任何已接通的 AI 工具帮你拿到预填好的代码片段:

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

First-run verification

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

你有哪些 espctl 工具?

预期:列出约 40 个工具(build、doctor、store_versions、 project.init 等等)。

Troubleshooting

“没有工具“或“espctl 启动失败” → 自己在终端里跑一下 espctl mcp serve,看它打印了什么错(常见原因:二进制找不到、 cwd 不对)。
列出了工具但每次调用都报“auth required“ → 你的 MCP_AUTH_SECRET 缺失或已失效。回到控制面重新签发一份访问密钥再填进配置。
项目级配置不生效 → Claude Code 只在从项目目录启动时才读取 <项目>/.claude/settings.json。先 cd <项目> 再 claude,而不是从外面指向项目。

更详细的检查清单见故障排查。

Tested as-of 2026-05-19

项目级 vs 全局配置

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

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

接下来问 Claude 什么

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

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

Keyboard shortcuts

ESPCTL MCP 用户手册