🚀 ESP32串行MCP电桥
通过Claude Code进行人工智能驱动的ESP32 MicroPython开发
一个完整的模型上下文协议（MCP）桥，使Claude Code能够通过浏览器中的WebSerial API在ESP32设备上开发、上传和管理MicroPython程序。
🏗️ 建筑
Claude Code ──► MCP Client ──► WebSocket ──► Browser ──► WebSerial API ──► ESP32
▲ │
└───────── Response ────────┘✨ 特性
🔧 MCP集成
- 完整的MCP v1.0.0支持 -完整的JSON-RPC 2.0实现
- 5核心工具 -上传、执行、读取、重置和列出文件
- 实时通信 -基于WebSocket的双向数据流
- 错误处理 -全面的错误传播和恢复
🌐 现代Web界面
- VS代码样式UI -熟悉的开发环境
- 网络串行API -直接浏览器到ESP32通信
- 实时控制台 -实时REPL输出和交互
- 代码编辑器 -语法高亮显示和项目模板
🧪 测试与开发
- 模拟ESP32 -无硬件开发和测试
- 单元测试 -pytest的测试覆盖率超过95%
- 集成测试 -端到端工作流验证
- 性能测试 -并发请求处理
🚀 快速开始
1.安装依赖项
pip install -r requirements.txt2.启动网桥服务器
python esp32_bridge_server.py服务器在上运行 http://localhost:3000
3.打开浏览器界面
引导到 http://localhost:3000 Chrome或Edge浏览器（需要WebSerial）
4.连接ESP32
- 在web界面中单击“连接ESP32”
- 从列表中选择您的ESP32设备
- 选择波特率（默认值：115200）
5.配置克劳德代码
添加到您的Claude Code MCP配置中：
{
"mcpServers": {
"esp32-bridge": {
"command": "python",
"args": ["/workspace/mcp_client.py", "ws://localhost:3000"],
"env": {}
}
}
}📋 MCP工具
🔧 可用工具
| 工具 | 说明 | 参数 |
|---|---|---|
upload_code | 将MicroPython代码上传到ESP32 | code （字符串）， filename （可选） |
execute_command | 在REPL中执行命令 | command （字符串） |
read_console | 获取最近的控制台输出 | lines （可选，默认值：10） |
reset_device | 软复位ESP32 | 无 |
list_files | 列出文件系统文件 | 无 |
📝 Claude代码中的示例用法
Upload this LED blink code to my ESP32:
import time
from machine import Pin
led = Pin(2, Pin.OUT)
while True:
led.on()
time.sleep(0.5)
led.off()
time.sleep(0.5)Claude Code将自动：
- 将代码上传为
main.py - 验证上传
- 演示如何运行它
- 监控输出
🧪 测试
单元测试
# Run all tests
pytest tests/ -v
# Run specific test file
pytest tests/test_mcp.py -v
# Run with coverage
pytest tests/ --cov=mcp_handler --cov-report=html集成测试
# Start bridge server (Terminal 1)
python esp32_bridge_server.py
# Start mock ESP32 (Terminal 2)
python tests/mock_esp32.py
# Run integration tests (Terminal 3)
pytest tests/test_integration.py -v模拟开发
# Start mock ESP32 for development
python tests/mock_esp32.py --port 3001 --debug
# Test with curl
curl http://localhost:3001/health🏗️ 项目结构
esp32-webserial-bridge/
├── esp32_bridge_server.py # Main Flask WebSocket server
├── mcp_handler.py # MCP protocol implementation
├── mcp_client.py # Claude Code entry point
├── claude_code_config.json # MCP server configuration
├── requirements.txt # Python dependencies
├── templates/
│ └── esp32_bridge.html # Web interface
├── tests/
│ ├── test_mcp.py # Unit tests
│ ├── test_integration.py # Integration tests
│ └── mock_esp32.py # Mock ESP32 server
└── README.md # This file⚙️ 配置
环境变量
FLASK_DEBUG-启用Flask调试模式WEBSOCKET_URL-websocket服务器URL（默认值：WS://localhost:3000）MCP_TIMEOUT-MCP请求超时（秒）（默认值：30）
浏览器要求
- Chrome 89+ 或 边缘89+ 对于WebSerial API是必需的
- 需要HTTPS 生产中（使用ngrok进行测试）
🔧 发展
添加新的MCP工具
- 将工具定义添加到
_handle_tools_list()在……里面mcp_handler.py - 在中实现处理程序
_handle_tools_call() - 添加WebSocket通信逻辑
- 更新测试和文档
扩展Web界面
- 编辑
templates/esp32_bridge.html - CSS中的VS代码样式组件
- JavaScript中的WebSocket事件处理程序
模拟ESP32功能
- 模拟MicroPython REPL
- 文件系统操作
- 带有历史记录的控制台输出
- 程序执行模拟
🐛 故障排除
MCP配置
🔧 检查当前MCP配置
# List all configured MCP servers
claude mcp list
# Get details about the esp32-bridge server
claude mcp get esp32-bridge🔧 更新MCP服务器端口 如果ESP32网桥配置了错误的端口：
# Remove the existing configuration
claude mcp remove esp32-bridge -s local
# Add with correct port (3000)
claude mcp add esp32-bridge /workspace/venv/bin/python /workspace/mcp_client.py http://localhost:3000🔧 MCP服务器状态
- ✅ 已连接：服务器正在运行且可访问
- ✗ 连接失败：检查网桥服务器是否在正确的端口上运行
- MCP配置位置：
~/.claude.json（当地项目范围）
常见问题
🔴 不支持WebSerial API
- 使用Chrome 89+或Edge 89+
- 确保生产中的HTTPS
- 检查浏览器兼容性
🔴 未检测到ESP32
- 安装ESP32 USB驱动程序（CP2102、CH340、FTDI）
- 检查设备管理器/系统报告
- 尝试不同的USB端口
🔴 WebSocket连接失败
- 验证网桥服务器是否在端口3000上运行
- 检查防火墙设置
- 确保没有端口冲突
🔴 MCP客户端没有响应
- 检查配置中的WebSocket URL
- 验证已安装的Python依赖项
- 检查克劳德代码日志
调试模式
# Enable debug logging
python mcp_client.py --debug ws://localhost:3000
# Check server health
curl http://localhost:3000/health
# View WebSocket connections
curl http://localhost:3000/api/connections🤝 贡献
- 分叉存储库
- 创建特征分支:
git checkout -b feature/awesome-feature - 添加测试 对于新功能
- 运行测试套件:
pytest tests/ -v - 提交拉取请求
代码的风格
- python：遵循PEP 8，使用类型提示
- 脚本：ES6+，格式一致
- 测试：覆盖率高，描述清晰
📜 许可证
MIT许可证
🙏 致谢
- Anthropic -克劳德码与MCP协议
- Espressif -ESP32和MicroPython支持
- Web序列API -浏览器到设备通信
- Flask SocketIO -实时WebSocket通信
______________________________________________________________________
由以下材料制成❤️ ESP32和AI开发社区