ESP32 MCP Server Component

中文文档 | English

An ESP32 component that implements the Model Context Protocol (MCP) server, providing a standardized way for AI applications to integrate with ESP32 devices. This component enables your ESP32 to expose tools and resources that can be discovered and used by AI agents and applications.

🌟 Features

• 🚀 Simple API: Clean, intuitive interface for registering tools and resources
• 🔧 Dynamic Registration: Register tools and resources at runtime
• 📦 Modular Design: Standalone component, easy to integrate into existing projects
• 🌐 HTTP Transport: JSON-RPC 2.0 over HTTP for maximum compatibility
• 🔄 URI Templates: Support for parameterized resource URIs (e.g., sensor://{type}/{id})
• 📊 Real-time Monitoring: Built-in server statistics and health monitoring
• 🛡️ Memory Safe: Automatic memory management and cleanup
• ✅ Schema Validation: Built-in parameter validation using JSON schemas (similar to Zod)
• 🎯 MCP Compliant: Fully compliant with MCP specification 2025-06-18

🏗️ Architecture

The ESP32 MCP Server follows the standard MCP architecture:

┌─────────────────┐    HTTP/JSON-RPC    ┌─────────────────┐
│   MCP Client    │ ◄─────────────────► │  ESP32 MCP      │
│  (AI Agent)     │                     │    Server       │
└─────────────────┘                     └─────────────────┘
                                               │
                                        ┌─────────────────┐
                                        │   Your ESP32    │
                                        │   Application   │
                                        │  (Tools & Data) │
                                        └─────────────────┘

📦 Installation

Using ESP Component Registry (Recommended)

idf.py add-dependency "0x1abin/esp_mcp_server"

Manual Installation

1. Clone this repository into your project's components directory:

cd your_project/components
git clone https://github.com/0x1abin/esp-mcp-server.git esp_mcp_server

2. Include the component in your main CMakeLists.txt:

idf_component_register(
    SRCS "main.c"
    INCLUDE_DIRS "."
    REQUIRES esp_mcp_server
)

🚀 Quick Start

Basic Server Setup

#include "esp_mcp_server.h"

// Tool handler function
static cJSON* echo_tool_handler(const cJSON *arguments, void *user_data) {
    cJSON *message = cJSON_GetObjectItem(arguments, "message");
    
    cJSON *result = cJSON_CreateObject();
    cJSON *content_array = cJSON_CreateArray();
    cJSON *content = cJSON_CreateObject();
    
    cJSON_AddStringToObject(content, "type", "text");
    cJSON_AddStringToObject(content, "text", message->valuestring);
    
    cJSON_AddItemToArray(content_array, content);
    cJSON_AddItemToObject(result, "content", content_array);
    
    return result;
}

void app_main(void) {
    // Initialize WiFi (using ESP-IDF examples common)
    ESP_ERROR_CHECK(nvs_flash_init());
    ESP_ERROR_CHECK(esp_netif_init());
    ESP_ERROR_CHECK(esp_event_loop_create_default());
    ESP_ERROR_CHECK(example_connect());
    
    // Configure MCP server
    esp_mcp_server_config_t config = ESP_MCP_SERVER_DEFAULT_CONFIG();
    config.port = 80;
    config.server_name = "ESP32 MCP Server";
    config.server_version = "1.0.0";
    
    // Initialize server
    esp_mcp_server_handle_t server;
    ESP_ERROR_CHECK(esp_mcp_server_init(&config, &server));
    
    // Create input schema for validation
    cJSON *schema = schema_builder_create_object();
    schema_builder_add_string(schema, "message", "Message to echo", true);
    
    // Register echo tool
    esp_mcp_tool_config_t tool_config = {
        .name = "echo",
        .description = "Echoes back the provided message",
        .input_schema = schema,
        .handler = echo_tool_handler,
        .user_data = NULL
    };
    ESP_ERROR_CHECK(esp_mcp_server_register_tool(server, &tool_config));
    
    // Start the server
    ESP_ERROR_CHECK(esp_mcp_server_start(server));
    
    ESP_LOGI("MAIN", "MCP Server started on port %d", config.port);
}

Advanced Example with GPIO Control

// GPIO control tool with schema validation
static cJSON* gpio_control_handler(const cJSON *arguments, void *user_data) {
    cJSON *pin = cJSON_GetObjectItem(arguments, "pin");
    cJSON *state = cJSON_GetObjectItem(arguments, "state");
    
    // SDK layer guarantees parameters are validated
    int gpio_num = pin->valueint;
    bool gpio_state = cJSON_IsTrue(state);
    
    gpio_set_level(gpio_num, gpio_state ? 1 : 0);
    
    cJSON *result = cJSON_CreateObject();
    cJSON *content_array = cJSON_CreateArray();
    cJSON *content = cJSON_CreateObject();
    
    cJSON_AddStringToObject(content, "type", "text");
    
    char response[100];
    snprintf(response, sizeof(response), "GPIO %d set to %s", 
             gpio_num, gpio_state ? "HIGH" : "LOW");
    cJSON_AddStringToObject(content, "text", response);
    
    cJSON_AddItemToArray(content_array, content);
    cJSON_AddItemToObject(result, "content", content_array);
    
    return result;
}

// Register GPIO control tool with schema validation
cJSON *gpio_schema = schema_builder_create_object();
schema_builder_add_integer(gpio_schema, "pin", "GPIO pin number", 0, 39, true);
schema_builder_add_boolean(gpio_schema, "state", "GPIO state (true=HIGH, false=LOW)", true);

esp_mcp_tool_config_t gpio_tool = {
    .name = "gpio_control",
    .description = "Control ESP32 GPIO pins",
    .input_schema = gpio_schema,
    .handler = gpio_control_handler,
    .user_data = NULL
};
ESP_ERROR_CHECK(esp_mcp_server_register_tool(server, &gpio_tool));

🔧 API Reference

Server Lifecycle

// Initialize server (does not start HTTP server)
esp_err_t esp_mcp_server_init(const esp_mcp_server_config_t *config, 
                              esp_mcp_server_handle_t *server_handle);

// Start HTTP server after registering tools/resources
esp_err_t esp_mcp_server_start(esp_mcp_server_handle_t server_handle);

// Stop HTTP server (can be restarted later)
esp_err_t esp_mcp_server_stop(esp_mcp_server_handle_t server_handle);

// Cleanup and free all resources
esp_err_t esp_mcp_server_deinit(esp_mcp_server_handle_t server_handle);

Tool Registration

// Register a tool with optional schema validation
esp_err_t esp_mcp_server_register_tool(esp_mcp_server_handle_t server_handle, 
                                       const esp_mcp_tool_config_t *tool_config);

// Tool handler signature
typedef cJSON* (*esp_mcp_tool_handler_t)(const cJSON *arguments, void *user_data);

Resource Registration

// Register a resource
esp_err_t esp_mcp_server_register_resource(esp_mcp_server_handle_t server_handle, 
                                           const esp_mcp_resource_config_t *resource_config);

// Resource handler signature
typedef char* (*esp_mcp_resource_handler_t)(const char *uri, void *user_data);

Schema Validation (Built-in Zod-like API)

// Create schema objects
cJSON* schema_builder_create_object(void);

// Add typed fields with validation
esp_err_t schema_builder_add_string(cJSON *schema, const char *name, 
                                   const char *description, bool required);
esp_err_t schema_builder_add_integer(cJSON *schema, const char *name, 
                                    const char *description, int min, int max, bool required);
esp_err_t schema_builder_add_boolean(cJSON *schema, const char *name, 
                                    const char *description, bool required);

🎯 MCP Protocol Support

This component fully implements the MCP specification:

• Tools: Execute actions with side effects (returns JSON)
• Resources: Provide data content (returns string/binary)
• Prompts: Reusable templates (planned)
• JSON-RPC 2.0: Complete protocol compliance
• Error Handling: Standard error codes and messages
• Schema Validation: Input parameter validation

Supported MCP Methods

Method	Description	Status
initialize	Server initialization and capability negotiation	✅
tools/list	List available tools	✅
tools/call	Execute a tool	✅
resources/list	List available resources	✅
resources/read	Read resource content	✅
ping	Health check	✅

📊 Examples

The component includes a comprehensive example in examples/simple/ that demonstrates:

• WiFi connection setup
• MCP server initialization and configuration
• Tool registration with schema validation
• Resource registration with URI templates
• GPIO control integration
• ADC reading functionality
• Real-time server statistics

Running the Example

cd examples/simple
idf.py set-target esp32
idf.py menuconfig  # Configure WiFi credentials
idf.py build flash monitor

🔧 Configuration Options

typedef struct {
    uint16_t port;                    // HTTP server port (default: 8080)
    const char *server_name;          // Server identification
    const char *server_version;       // Server version
    size_t max_connections;           // Max concurrent connections
    size_t stack_size;                // HTTP server stack size
    int task_priority;                // HTTP server task priority
} esp_mcp_server_config_t;

// Default configuration macro
#define ESP_MCP_SERVER_DEFAULT_CONFIG() { \
    .port = 8080, \
    .server_name = "ESP32 MCP Server", \
    .server_version = "1.0.0", \
    .max_connections = 4, \
    .stack_size = 8192, \
    .task_priority = 5 \
}

🛡️ Security Considerations

• Parameter Validation: All tool inputs are validated against JSON schemas
• Memory Safety: Automatic cleanup of JSON objects and strings
• Error Handling: Comprehensive error reporting with standard HTTP/JSON-RPC codes
• Resource Limits: Configurable connection limits and timeouts

🧪 Testing

Test your MCP server using any MCP-compatible client:

# Using curl to test tools/list
curl -X POST http://your-esp32-ip/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Using curl to call a tool
curl -X POST http://your-esp32-ip/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"echo","arguments":{"message":"Hello World"}}}'

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Projects

• Model Context Protocol Specification
• ESP-IDF
• cJSON

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• ESP32 Forum: Espressif Forum

---

Made with ❤️ for the ESP32 and AI community