ESP-Workspace MCP
A full autonomous embedded firmware workspace server — the MCP (Model Context Protocol) infrastructure layer for AI agents working with ESP-IDF projects.
What it does
ESP-Workspace MCP turns an AI coding assistant into an autonomous firmware engineer. It provides tools for:
- Filesystem operations — read, write, list, glob with path sandboxing
- Shell execution — run commands with timeout, background jobs, output capture
- ESP-IDF build system — build, flash, clean, reconfigure via
eim runwithWISH_PRODUCTsupport - Security — Bearer token auth, path traversal prevention, configurable filesystem roots
Quick Start
Prerequisites
- Python 3.10+
- Espressif Install Manager (
eim— handles ESP-IDF installation and environment setup
Installation
pip install esp-workspace-mcp
Or from source:
git clone https://github.com/AIRcableLLC/esp-workspace-mcp.git
cd esp-workspace-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
Configuration
Create a .env file:
MCP_API_TOKEN=your-secret-token-here
MCP_HOST=0.0.0.0
MCP_PORT=8765
MCP_ALLOWED_ROOTS=/home/user/projects
MCP_WISH_PRODUCT=TargetS3
MCP_EIM_PATH=eim
Or set environment variables directly.
Run the server
# SSE mode (default, for network access)
python run_server.py
# Stdio mode (for local MCP clients)
python run_server.py --stdio
The server exposes:
GET /sse— SSE connection endpoint (requires Bearer token)POST /messages— MCP message endpointGET /health— health check (no auth required)
MCP Tools
Filesystem Tools
| Tool | Description |
|---|---|
read_file(path, offset, limit) |
Read text file with pagination |
write_file(path, content) |
Write content to a file |
append_file(path, content) |
Append to an existing file |
list_dir(path) |
List directory entries |
create_dir(path) |
Create directory recursively |
delete_path(path) |
Delete file or empty directory |
file_stat(path) |
Get file/directory metadata |
glob_search(pattern, path) |
Find files by glob pattern |
Shell Tools
| Tool | Description |
|---|---|
run_command(cmd, cwd, timeout) |
Execute command and wait |
start_process(cmd, cwd) |
Start background job |
get_job_output(job_id, offset) |
Read job output |
kill_job(job_id) |
Terminate background job |
list_jobs() |
List all jobs |
ESP-IDF Tools
All ESP-IDF operations are invoked through eim run "WISH_PRODUCT=<product> idf.py ..." which handles environment setup automatically.
| Tool | Description |
|---|---|
eim_run(commands, project_dir, wish_product) |
Run any idf.py command via eim |
build_project(project_dir, wish_product, reconfigure) |
Build an ESP-IDF project |
set_target(project_dir, target, wish_product) |
Set target chip (esp32, esp32s3, etc.) |
flash_project(project_dir, port, wish_product) |
Flash firmware to device |
clean_project(project_dir) |
Clean build artifacts |
fullclean_project(project_dir) |
Remove entire build directory |
reconfigure_project(project_dir, wish_product) |
Regenerate sdkconfig + CMake cache |
Build Step Decision Tree
Is sdkconfig missing or have defaults changed?
├── YES → eim_run("reconfigure build", project_dir, wish_product)
└── NO → eim_run("build", project_dir, wish_product)
Security
| Control | Implementation |
|---|---|
| Filesystem sandbox | All paths validated against MCP_ALLOWED_ROOTS |
| Path traversal prevention | Symlink-resolved, .. escapes rejected |
| Shell timeout | Configurable, default 30s, max 300s |
| Output truncation | 50 KB max per response |
| Authentication | Bearer token on every request |
| Credential safety | Tokens in env vars only, never logged |
Integration with AI Agents
Hermes
hermes mcp add esp-workspace \
--url http://host:port/sse \
--header "Authorization: Bearer your-token"
Generic MCP Client
Any MCP-compatible client can connect to the SSE endpoint. The server implements the standard MCP protocol over SSE/HTTP transport.
Architecture
esp_workspace_mcp/
├── config.py # Settings from env, fail-fast validation
├── server.py # FastMCP server, tool registration
├── auth.py # Bearer token middleware
├── tools/
│ ├── filesystem.py # 8 path-validated file operations
│ ├── shell.py # Command execution + background jobs
│ └── esp_idf.py # eim-run wrapper, build/flash/clean
├── utils/
│ ├── security.py # Path sandboxing, symlink resolution
│ └── process.py # Subprocess management, JobManager
└── resources/
└── project.py # MCP resources (project status, etc.)
License
Apache-2.0
Metadata
Release files for esp-workspace-mcp 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| esp_workspace_mcp-1.1.0.tar.gz | 43.9 kB | Without provenance | Details for esp_workspace_mcp-1.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| esp_workspace_mcp-1.1.0-py3-none-any.whl | Python 3 | none | any | Details for esp_workspace_mcp-1.1.0-py3-none-any.whl |
Total release size: 97.3 kB
Release files / esp_workspace_mcp-1.1.0.tar.gz
| Download URL | esp_workspace_mcp-1.1.0.tar.gz |
|---|---|
| Size | 43.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
42e0a7f8af8d43482e9c837362b65e130a8a1a2a1cfa551f6421922a3eeb2c20
|
|
BLAKE2b-256 checksum How to use checksums |
a091195503db5a01d08ecf368b4bfcfb818405a65c4942f56561e1f7238773ab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / esp_workspace_mcp-1.1.0-py3-none-any.whl
| Download URL | esp_workspace_mcp-1.1.0-py3-none-any.whl |
|---|---|
| Size | 53.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
48abe5282d61441e1d04011da287163b5e5ee2be2c49e85b3a2d68f987b845b8
|
|
BLAKE2b-256 checksum How to use checksums |
b1d98c4da3f47f6a1e7530e9f1832244f371c5119729a10939af60db6d8575f4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Security for esp-workspace-mcp 1.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.