Content
# ESP32 Toolkit MCP Server
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
An MCP (Model Context Protocol) server that equips AI coding assistants with deep ESP32 knowledge. Ships with 5 tools covering pin mapping, framework detection, dependency analysis, code generation, and error parsing.
## Features
| Tool | Description | Use Case |
|------|-------------|----------|
| `esp32_pin_map` | GPIO pin mapping for ESP32/ESP32-S3/ESP32-C3 | Find pin functions, constraints, ADC channels |
| `esp32_detect_framework` | Detect build framework of ESP32 project | Auto-detect Arduino vs ESP-IDF vs PlatformIO |
| `esp32_analyze_deps` | Analyze dependencies and detect conflicts | Review PlatformIO library dependencies |
| `esp32_generate_code` | Generate boilerplate code templates | WiFi STA/AP, MQTT, BLE, I2C, SPI, OTA, Web Server |
| `esp32_parse_error` | Parse common errors with actionable fixes | Fix compilation, linker, stack overflow issues |
## Supported Chips
- **ESP32 WROOM-32** — Dual-core Xtensa LX6, WiFi + Classic Bluetooth
- **ESP32-S3** — Dual-core Xtensa LX7, USB OTG, LCD interface support
- **ESP32-C3** — Single-core RISC-V, compact form factor
## Quick Start
```bash
# Install dependencies
npm install
# Start the server
npm start
```
## Configuration
Add to your MCP client configuration:
```json
{
"mcpServers": {
"esp32-toolkit": {
"command": "node",
"args": ["path/to/esp32-mcp-server/index.js"]
}
}
}
```
Supported clients: Codex CLI, Cursor IDE, VS Code MCP extension, any MCP-compatible tool.
## Tools in Detail
### esp32_pin_map
Returns detailed GPIO information including functions, ADC channels, boot constraints, and input-only warnings.
```
Input: { model: "esp32", pin: 2 }
Output: GPIO2 pin map with I2C_STD function, ADC2_CH2, and boot constraint info
```
Aliases supported: `esp32wroom32`, `esp32s3devkitc`, `esp32c3`, etc.
### esp32_detect_framework
Analyzes a project directory to determine build system (PlatformIO/CMake) and framework (Arduino/ESP-IDF).
```
Input: { projectPath: "/path/to/esp32-project" }
```
Checks: `platformio.ini`, `CMakeLists.txt`, `sdkconfig`, and `components/` directory.
### esp32_analyze_deps
Extracts all library dependencies from a PlatformIO project's `platformio.ini`.
```
Input: { projectPath: "/path/to/project" }
```
Returns dependency list with popular library recommendations.
### esp32_generate_code
Generates production-ready boilerplate code for common ESP32 tasks.
Available templates:
- `wifi_sta` — WiFi Station connection with auto-reconnect
- `wifi_ap` — Access point mode
- `mqtt_client` — MQTT subscriber/publisher
- `ble_scanner` — BLE device discovery
- `i2c_sensor` — I2C bus scanner
- `web_server` — HTTP server
- `ota_update` — WiFi OTA firmware update
- `spi_display` — ST7735 SPI display
```
Input: { framework: "arduino", template: "wifi_sta", config: { ssid: "MyWiFi", password: "secret" } }
```
### esp32_parse_error
Analyzes compiler/linker error messages and returns category + fix suggestions.
```
Input: { errorMessage: "stack overflow detected in task xyz" }
```
## Architecture
```
esp32-mcp-server/
├── index.js # Main MCP server (240 lines)
├── data/
│ ├── pins.json # GPIO pin definitions (all 3 chips)
│ ├── errors.json # Error pattern detection rules
│ └── templates.json # Code generation templates
├── package.json # NPM manifest
├── .gitignore # node_modules, .env
├── LICENSE # MIT License
└── README.md # This file
```
The entire server is a single entry point (`index.js`). All static data lives in JSON files for easy maintenance and extension.
## Security
- Runs entirely locally with no external network requests
- Pin data and templates are loaded from local files
- Framework detection reads only the specified project directory
- No credential storage or external API calls
## Contributing
Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Submit a Pull Request
For new chip support, add pin data to `data/pins.json` using the existing format. For new code templates, extend `data/templates.json` and the template substitution helper.
## License
MIT License - see [LICENSE](LICENSE) for details.
