ESP Pilot MCP

Introduction to ESP Pilot MCP

ESP Pilot MCP is a read-only MCP service for AI assistants, identified by esp-pilot-mcp, with the current version being 0.5.0. It organizes the devices, peripherals, development boards, and YAML templates of ESP Board Manager, as well as the capabilities, components, and examples of ADF/GMF into a searchable directory for clients such as Cursor, Codex, Claude Code to call when writing board-level configurations or selecting multimedia components.

Addresses:

Division of Labor with Other Espressif MCPs

When ESP Pilot MCP is used in conjunction with other Espressif MCPs, their responsibilities can be distinguished as follows:

ESP Pilot MCP: Select BMGR device/peripheral/development board, get YAML template, select ADF/GMF components and examples, load Skills as needed.
Espressif Documentation MCP: Search for official documents such as ESP-IDF, ESP-ADF, ESP Board Manager.
ESP Component Registry MCP: Find and understand third-party or official components in the component repository.

The common combination for multimedia board-level adaptation is: ESP Pilot MCP is responsible for “what to choose, how to write YAML”, Documentation MCP is responsible for “how to search for API and documents”, and local idf.py bmgr / idf.py build is responsible for verification.

Feature Characteristics

Dynamic Skill Loading

You can dynamically load board-manager-create-board, board-manager-use and esp-hardware-app-platform-workflow and other subsequent ADF/GMF component-related Skills as needed through catalog_get_skill.

It does not replace official document retrieval. README, API and example source code still go through Espressif Documentation MCP, or read according to the returned github_url / api_docs_url.

Access Method

Cursor ~/.cursor/mcp.json：

{
    "mcpServers": {
        "esp-pilot-mcp": {
            "url": "https://mcp.esp-pilot.espressif.com/mcp"
        }
    }
}

Codex：

codex mcp add esp-pilot-mcp --url "https://mcp.esp-pilot.espressif.com/mcp"

Claude Code：

claude mcp add --transport http "esp-pilot-mcp" "https://mcp.esp-pilot.espressif.com/mcp"

Tools

BMGR Tools：

catalog_list_bmgr_devices：List devices, can be filtered by type, interface, chip, IDF version.
catalog_list_bmgr_peripherals：List peripherals, can be filtered by type, role, format, chip, IDF version.
catalog_list_bmgr_boards：List development board signatures.
catalog_list_socs：List SoC and available IDF profiles.
catalog_get_bmgr_doc：Get RST by section. First section=overview, after selecting the mode, get min_config or full_fields; for debugging/code/board-level reference/API and other remaining sections, use section=heading.

ADF/GMF Tools：

catalog_list_adf_gmf_capabilities：List capabilities, return name / layer / category / first paragraph of summary.
catalog_get_adf_gmf_capability：Get feature list or remaining introduction, as well as registry / github_url / docs_url / optional api_docs_url.
catalog_list_adf_gmf_scenarios：List ADF multimedia examples (name, category, introduction, GitHub URL). There is no corresponding get tool, the source code directly opens github_url.

Others：

catalog_list_skills / catalog_get_skill：List or read three vendored skills. catalog_get_skill returns SKILL.md and sub-file list when resources is not passed; pass in resources to get the corresponding original text.
server_info：Metadata of the currently loaded product, can be used to check the catalog generation time.

Problems Solved in the Development Process

ESP Pilot MCP does not generate code or execute builds, but it can provide verifiable directories, templates, and workflows for AI assistants before and during development. For example, in multimedia applications, you can use it in the following ways:

Configure the development board: First, query available devices, peripherals, and existing development boards according to the chip, device type, and interface; then use catalog_get_bmgr_doc to get the minimum YAML configuration or complete field description for the corresponding mode. The AI assistant fills in board_devices.yaml and board_peripherals.yaml based on this, instead of guessing field names, enumeration values, or interface combinations from memory. IO, addresses, and timing must still be based on the schematic and device datasheet.
Start by looking for reusable implementations before writing the project: Search for the capabilities, components, and examples of ADF/GMF according to the requirements such as playback, recording, display, etc., and obtain their categories, introductions, and links to repositories and documents. This way, you can first confirm whether the existing components or examples cover the requirements, and then decide whether to reuse, combine, or implement them yourself, avoiding the duplication of existing capabilities.
Advance development work in stages: When you need to advance from hardware adaptation to application development, you can load esp-hardware-app-platform-workflow as needed. This skill strings the requirements confirmation, hardware information check, board-level YAML, ADF/GMF application design and writing, build verification, and review into a phased process, clarifying what to query, modify, and how to verify at each step.
Locate configuration issues: When the Board Manager generation or build fails, you can look back at the field descriptions, constraints, and corresponding skills in the catalog, confirm the YAML mode, peripheral dependencies, and configuration items; the actual generation and build are still completed by the local idf.py bmgr and idf.py build.

Therefore, the main problems that ESP Pilot MCP solves are the incompleteness and inaccuracy of information before development decisions:

Device, peripheral, YAML field, component, and example information come from the current catalog, which can be filtered by chip.
Board-level configuration has templates and field descriptions corresponding to the device mode, and components and examples have repositories and document entrances for further verification.
Board building, project access, and the connection from hardware to application can be selected according to the task by choosing the appropriate skill, reducing the situation of missing key confirmations and verification steps.

Skills

Three skills are released with the catalog, loaded as needed by catalog_get_skill, do not pre-read the whole package:

board-manager-create-board: Write BMGR board definition from schematic / BOM / pin table, or from existing BSP source code. Verify with idf.py bmgr -b, do not go through -n scaffold.
board-manager-use: Connect an existing BMGR board in an existing project: add dependencies, select boards, generate, get handles, use amend for minor changes, and troubleshoot in stages. Not responsible for building boards from scratch.
esp-hardware-app-platform-workflow: An end-to-end entry from requirement confirmation, hardware evidence, board-level YAML, to ADF/GMF application design, writing, validation, and review.

Precautions

The public network catalog is updated with deployment, which may be slightly behind the ESP Board Manager, ESP-GMF, ESP-ADF document source. You can use server_info to view generated_at.
catalog_get_bmgr_doc returns the recipe and field description, not the complete driver implementation. The init of stock devices is still generated by BMGR, do not rewrite in setup_device.c.
The same logical audio_codec device cannot enable adc_enabled and dac_enabled at the same time. Full duplex needs to be split into two unidirectional devices. These constraints are written in the overview, and you need to get the document chunks before writing YAML.