Claude Desktop

桌面版 Claude 应用通过一个全局配置文件支持 espctl。

配置

编辑(或创建)以下文件:

把 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 那一章一样。

看看是不是工作了

完全退出 Claude Desktop(macOS 上是 Cmd+Q,不是关闭窗口),再重新 打开,让新配置生效。然后在任意对话里:

列出 espctl 工具。

如果看到 “no tools” 或 “espctl failed to start”,点击消息输入框旁边 的小拼图/插头图标 —— Claude Desktop 在那里展示实时状态和每个服务 的最近错误。

Claude Desktop 特有注意事项

• Claude Desktop 是单配置工具 —— 没有项目级覆盖。如果你在多个芯片 不同的 ESP-IDF 项目之间切换,最简单的做法是把 cwd 指向一个 “当前项目“软链,在不同项目之间手动切换。或者用 Claude Code, 它有项目级配置。
• 你在 shell(~/.zshrc、~/.bashrc)里设置的环境变量在 macOS 上 不会被 GUI 应用继承。永远把每个变量直接列在 env 块里。

提示

问 Claude:

读取 install://claude-desktop 资源。

…拿到一份按你机器预填好的可粘贴配置。