Server Tools

The server exposes 3 meta-tools for inspecting the running mcesptool instance: server information, tool discovery, and environment health checks. These tools do not interact with hardware and are always available.

---

esp_server_info

Get comprehensive information about the running server including version, uptime, loaded components, tool count, and available capabilities.

Parameters

This tool takes no parameters.

Example

result = await client.call_tool("esp_server_info", {})

Return Value

{
  "server_name": "MCP ESPTool Server",
  "version": "2026.02.23",
  "uptime_seconds": 1234.56,
  "configuration": {
    "esptool_path": "esptool",
    "esp_idf_path": "/home/user/esp/esp-idf",
    "project_roots": ["/home/user/esp_projects"],
    "default_baud_rate": 460800,
    "connection_timeout": 30,
    "enable_stub_flasher": true,
    "max_concurrent_operations": 5,
    "production_mode": false,
    "idf_available": true,
    "qemu_available": true,
    "qemu_xtensa_path": "/home/user/.espressif/tools/qemu-xtensa/.../qemu-system-xtensa",
    "qemu_riscv_path": "/home/user/.espressif/tools/qemu-riscv32/.../qemu-system-riscv32"
  },
  "components": [
    "chip_control", "flash_manager", "partition_manager",
    "security_manager", "firmware_builder", "ota_manager",
    "production_tools", "diagnostics", "qemu_manager"
  ],
  "total_tools": 44,
  "total_resources": 3,
  "esp_idf_available": true,
  "production_mode": false,
  "capabilities": {
    "chip_detection": true,
    "flash_operations": true,
    "partition_management": true,
    "security_features": true,
    "ota_updates": true,
    "factory_programming": true,
    "host_applications": true,
    "qemu_emulation": true
  }
}

Capabilities

Capability	When available
chip_detection	Always
flash_operations	Always
partition_management	Always
security_features	Always
ota_updates	Always
factory_programming	Always
host_applications	When ESP-IDF is detected
qemu_emulation	When QEMU binaries are detected

---

esp_list_tools

List all available MCP tools, optionally filtered by component category. Useful for tool discovery and documentation generation.

Parameters

Name	Type	Default	Description
category	str | None	None	Filter by category name. Returns all categories if omitted.

Categories

Category	Tools
chip_control	esp_detect_chip, esp_connect_advanced, esp_reset_chip, esp_load_test_firmware
flash_operations	esp_flash_firmware, esp_flash_read, esp_flash_erase, esp_flash_backup
partition_management	esp_partition_create_ota, esp_partition_custom, esp_partition_analyze
security	esp_security_audit, esp_enable_flash_encryption, esp_efuse_read, esp_efuse_burn
firmware	esp_elf_to_binary, esp_firmware_analyze
ota	esp_ota_package_create, esp_ota_deploy, esp_ota_rollback
production	esp_factory_program, esp_batch_program, esp_quality_control
diagnostics	esp_memory_dump, esp_performance_profile, esp_diagnostic_report
qemu_emulation	esp_qemu_start, esp_qemu_stop, esp_qemu_list, esp_qemu_status, esp_qemu_flash

The qemu_emulation category is only present when QEMU binaries are available. If ESP-IDF is detected, an additional esp_idf category appears with IDF-specific tools.

Example

# List all categories
result = await client.call_tool("esp_list_tools", {})

# List tools in a specific category
result = await client.call_tool("esp_list_tools", {
    "category": "flash_operations"
})

Return Value

All categories:

{
  "total_categories": 9,
  "categories": {
    "chip_control": ["esp_detect_chip", "esp_connect_advanced", "..."],
    "flash_operations": ["esp_flash_firmware", "esp_flash_read", "..."],
    "...": "..."
  },
  "total_tools": 44
}

Filtered by category:

{
  "category": "flash_operations",
  "tools": ["esp_flash_firmware", "esp_flash_read", "esp_flash_erase", "esp_flash_backup"]
}

Unknown category:

{
  "error": "Unknown category: nonexistent",
  "available_categories": ["chip_control", "flash_operations", "..."]
}

---

esp_health_check

Perform an environment health check. Verifies esptool availability, ESP-IDF installation, and project directory accessibility. With detailed: true, also checks the health of each loaded component.

Parameters

Name	Type	Default	Description
detailed	bool	False	Include per-component health checks.

Example

result = await client.call_tool("esp_health_check", {
    "detailed": True
})

Return Value

{
  "status": "healthy",
  "timestamp": 1708732800.0,
  "checks": {
    "esptool": {
      "available": true,
      "version": "esptool.py v4.8"
    },
    "esp_idf": {
      "available": true,
      "path": "/home/user/esp/esp-idf"
    },
    "project_roots": {
      "configured": 2,
      "accessible": 2
    }
  },
  "components": {
    "chip_control": {"status": "healthy", "esptool_path": "esptool"},
    "flash_manager": {"status": "healthy", "note": "Flash manager ready"},
    "partition_manager": {"status": "healthy", "note": "Partition manager ready"},
    "security_manager": {"status": "healthy", "note": "Security manager ready"},
    "firmware_builder": {"status": "healthy", "note": "Firmware builder ready"},
    "ota_manager": {"status": "healthy", "note": "OTA manager ready"},
    "production_tools": {"status": "healthy", "note": "Production tools ready"},
    "diagnostics": {"status": "healthy", "note": "Diagnostics ready"},
    "qemu_manager": {
      "status": "healthy",
      "qemu_xtensa_available": true,
      "qemu_riscv_available": true,
      "running_instances": 0,
      "max_instances": 4
    }
  }
}

Health Status

Status	Meaning
healthy	All checks passed.
degraded	Some non-critical checks failed (e.g., ESP-IDF not installed).

The components object is only present when detailed is True. The failed_checks array is only present when status is "degraded".