Cursor
Why this agent
Cursor 是基于 VS Code、原生支持 MCP 的代码感知 IDE。把 espctl 接通后,Cursor 的聊天面板就能驱动 ESP-IDF 构建、读 日志、烧固件 —— 全在编辑器里完成。
Prerequisites
- 已安装 Cursor(任何支持 MCP 的 0.40+ 版本)。
espctl已安装在磁盘上某个稳定位置(下文需要完整路径)。- (可选,用于远程构建)Aegis 构建服务器地址 +
MCP_AUTH_SECRET。
Install snippet (or alternative)
写入工作区的 .cursor/mcp.json,或者 ~/.cursor/mcp.json 让 espctl
在所有 Cursor 工作区中可用:
{
"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"
}
}
}
}
每个字段填什么:
command——espctl程序的完整路径。cwd—— Cursor 应该操作的 ESP-IDF 项目的完整路径。CONTROL_BASE_URL+MCP_AUTH_SECRET—— 两个都留空就是仅计划模式; 两个都设就是远程构建。
或者 —— 通过 MCP 资源拿到预填片段:
读取
install://cursor资源。
First-run verification
重启 Cursor。打开聊天面板问:
你有哪些 espctl 工具?
预期:列出约 40 个工具(build、doctor、store_versions 等等)。
Troubleshooting
- 工具列表为空或 “espctl failed to start” → 看 Cursor 的 MCP
日志面板(Output → MCP),
espctl mcp serve的实际错误在那里。 - shell 里设的环境变量在 Cursor 里看不见 → 如果你把 Cursor 锁到
某个特定 shell(例如
fish),Cursor 可能不继承你的~/.zshrc/~/.bashrc导出。把每个变量直接列在env块里。 - 工作区级 vs 全局 → Cursor 的 MCP 支持是工作区级。项目级
.cursor/mcp.json是最常见的做法。