Claude Desktop
Why this agent
Claude Desktop 是 Anthropic 的 Claude 桌面端 GUI 客户端。把 espctl 接通后,Claude Desktop 任意对话都能驱动固件构建 —— 适合喜欢对话窗 UX 多于终端 CLI 的用户。
Prerequisites
- 已安装 Claude Desktop(macOS、Windows 或 Linux)。
espctl已安装在磁盘上某个稳定位置(下文需要完整路径)。- (可选,用于远程构建)Aegis 构建服务器地址 +
MCP_AUTH_SECRET。
Install snippet (or alternative)
桌面版 Claude 应用通过一个全局配置文件支持 espctl。编辑(或创建) 以下文件:
| 平台 | 路径 |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json |
把 espctl 条目并入 mcpServers map(没有就创建):
{
"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/... 替换成你电脑上的完整路径。字段含义和
Claude Code 那一章一样。
或者 —— 拿到预填好的代码片段:
读取
install://claude-desktop资源。
First-run verification
完全退出 Claude Desktop(macOS 上是 Cmd+Q,不是关闭窗口),再重新 打开,让新配置生效。然后在任意对话里:
列出 espctl 工具。
预期:列出约 40 个工具。
Troubleshooting
- “no tools” 或 “espctl failed to start” → 点击消息输入框旁 边的小拼图/插头图标;Claude Desktop 在那里展示实时状态和每个 MCP 服务的最近错误。常见原因:GUI 应用不继承 shell 设置的环境 变量。
- shell 设的环境变量看不见 → 在 macOS 上,你在 shell
(
~/.zshrc、~/.bashrc)里设置的环境变量 GUI 应用不会 继承。永远把每个变量直接列在env块里。 - 没有项目级覆盖 → Claude Desktop 是单配置工具。如果你在
多个芯片不同的 ESP-IDF 项目之间切换,最简单的做法是把
cwd指向一个“当前项目“软链。或者改用 Claude Code,它有项目级配置。