Esp32 Station

ESP32 MicroPython开发站

基于Raspberry Pi的MCP服务器，用于管理运行MicroPython的ESP32板。主机上的Claude可以闪存固件、部署代码，并通过局域网与电路板交互——无需终端切换，也无需复制粘贴工具输出。

它做什么

• 刷写固件 --将MicroPython闪存到任何连接的ESP32（经典、S2、S3、C3、C6）上；根据芯片类型自动选择正确的固件；固件在本地缓存，具有7天TTL
• 部署代码 --通过USB串行将单个文件或完整项目目录部署到板上
• REPL访问 --执行MicroPython命令并捕获输出；读取最近的串行输出；软/硬重置
• OTA更新 --通过WebREPL通过WiFi推送代码更新；超时时回退到USB *（第三阶段）*
• GitHub部署 --从GitHub仓库中提取最新代码，并在一次工具调用中部署到板上 *（第三阶段）*

所有功能都以MCP工具的形式公开——Claude直接调用它们，不需要复制粘贴。

需求

• 运行Python 3.10+的Linux机器（Raspberry Pi、ARM SBC或x86）
• 系统守护进程
• 通过USB连接的ESP32板
• 配置了MCP的主机上的Claude代码

设置

快速设置（推荐）

在Pi上运行安装脚本。它处理一切：克隆仓库，创建虚拟环境，安装依赖项，将您添加到 dialout 组，提示输入WiFi凭据，自动生成WebREPL密码，并安装+启动systemd服务。

curl -fsSL https://raw.githubusercontent.com/bakedpanda/esp32-station/main/setup.sh | bash

或者先克隆并在本地运行：

git clone https://github.com/bakedpanda/esp32-station.git esp32-station
bash esp32-station/setup.sh

脚本打印 claude mcp add 最后的命令--copy将其粘贴到您的主机上以注册服务器。

WebREPL密码会自动生成并存储在 /etc/esp32-station/wifi.json。如果您需要它（例如从浏览器手动连接到WebREPL），请使用以下方式查找：

sudo cat /etc/esp32-station/wifi.json

手动设置（回退）

如果你喜欢一步一步地做：

1.克隆并安装依赖项

git clone https://github.com/bakedpanda/esp32-station.git esp32-station
cd esp32-station
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2.添加串口权限

sudo usermod -aG dialout $USER
# Log out and back in for this to take effect

3.创建WiFi凭据文件

sudo mkdir -p /etc/esp32-station
sudo tee /etc/esp32-station/wifi.json << 'EOF'
{"ssid": "YOUR_SSID", "password": "YOUR_WIFI_PASSWORD", "webrepl_password": "YOUR_WEBREPL_PASS"}
EOF
# WebREPL password can be anything — pick something or generate one:
# python3 -c "import secrets, string; print(''.join(secrets.choice(string.ascii_letters + string.digits) for _ in range(12)))"
sudo chmod 600 /etc/esp32-station/wifi.json

4.安装systemd服务

编辑 esp32-station.service 替换 User=esp32 和 /home/esp32 使用您的实际用户名和主目录，然后：

sudo cp esp32-station.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable esp32-station
sudo systemctl start esp32-station

5.使用Claude Code注册（在您的主机上）

claude mcp add --transport http esp32-station http://raspberrypi.local:8000/mcp

替换 raspberrypi.local 使用Pi的实际主机名或IP地址。使用查找主机名 hostname 以及IP hostname -I.

MCP工具

建筑

Main machine (Claude Code)
    │  MCP over Streamable HTTP
    ▼
Raspberry Pi :8000
    ├── mcp_server.py         — FastMCP tool registration
    └── tools/
        ├── board_detection.py  — USB enumeration, chip ID (esptool)
        ├── firmware_flash.py   — Firmware cache + flash (esptool)
        ├── file_deploy.py      — File/dir deploy (mpremote)
        ├── repl.py             — REPL exec, serial read, reset (mpremote)
        ├── serial_lock.py      — Per-port file lock (prevents USB conflicts)
        ├── ota_wifi.py         — WiFi OTA deploy (webrepl_cli.py subprocess)
        ├── github_deploy.py    — GitHub clone + deploy (git + deploy_directory)
        ├── board_status.py     — Board status queries (firmware, WiFi, memory, storage)
        ├── webrepl_cmd.py      — WebREPL command transport (over-WiFi REPL)
        ├── mdns_discovery.py   — mDNS board discovery via python-zeroconf
        ├── credentials.py      — WiFi + WebREPL credential loading from Pi-local file
        └── boot_deploy.py      — boot.py template generation and deployment
    │
    ▼
ESP32 board(s) via USB

关键决策：

• MCP over Streamable HTTP（非stdio）——可通过curl调试，在局域网上工作
• 每个端口串行锁定——对不同板的并发工具调用工作正常；相同的板调用安全序列化
• 子进程隔离——esptool、mpremote和git作为子进程运行；比进程内绑定更干净
• 切勿依赖esptool自动检测——芯片变体在闪烁前已明确提供或验证

运行测试

source venv/bin/activate
pytest

状态

超出范围

• Web UI/仪表板——Claude是界面
• 车队库存/多板跟踪——一次单板
• 非MicroPython固件（Arduino、ESP-IDF、Zephyr）
• 身份验证/安全强化——仅限受信任的局域网