ESP-IDF MCP over MQTT SDK

August 11, 2025 · View on GitHub

English | 中文

An implementation of Model Context Protocol (MCP) over MQTT 5.0 for ESP32 platform, developed based on the ESP-IDF framework.

What is MCP?

Model Context Protocol (MCP) is an open protocol for secure, structured communication between AI assistants and external data sources and tools. MCP allows AI assistants to:

  • Access external data sources and knowledge bases
  • Invoke external tools and services
  • Operate within secure boundaries
  • Interact with multiple data sources in a standardized way

MCP defines clear interfaces and protocols, enabling AI assistants to safely extend their capabilities while maintaining control over data access.

Why MCP over MQTT?

MQTT is a lightweight messaging protocol designed for IoT and edge computing. Combining MCP with MQTT brings the following advantages:

Core Features

  • Lightweight Transport: Suitable for bandwidth-constrained network environments
  • Reliable Message Delivery: Supports QoS levels and message persistence
  • Built-in Service Discovery: MCP clients can automatically discover available MCP servers
  • Load Balancing and Scalability: Supports horizontal scaling of MCP server instances
  • Flexible Access Control: Implements fine-grained authorization through MQTT topic permissions

Use Cases

  • Edge Computing: Deploy MCP servers on resource-constrained devices
  • IoT Applications: Provide AI capabilities for smart devices
  • Cloud-Edge Collaboration: Seamless integration between cloud AI and edge devices
  • Real-time Communication: Support low-latency AI tool invocation

SDK Features

Core Functionality

  • MCP Server: Complete MCP protocol implementation
  • MQTT 5.0 Support: Based on ESP-IDF MQTT client
  • Tool Registration: Support dynamic registration and invocation of MCP tools
  • Resource Management: Provide data resource access capabilities
  • JSON-RPC: Communication protocol based on JSON-RPC 2.0

Tool System

typedef struct {
    char *name;                    // Tool name
    char *description;             // Tool description
    int property_count;            // Number of parameters
    property_t *properties;        // Parameter definitions
    const char *(*call)(int n_args, property_t *args); // Execution function
} mcp_tool_t;

Resource Management

typedef struct {
    char *uri;                     // Resource URI
    char *name;                    // Resource name
    char *description;             // Resource description
    char *mime_type;               // MIME type
    char *title;                   // Resource title
} mcp_resource_t;

Security Features

  • TLS/SSL Support: Support for MQTTS secure connections
  • User Authentication: Username/password authentication
  • Certificate Verification: Client certificate support
  • Access Control: Permission management based on MQTT topics

Installation and Dependencies

System Requirements

  • ESP-IDF v5.0 or higher
  • ESP32 series chips
  • MQTT Broker supporting MQTT 5.0

Dependencies

REQUIRES:
  - mqtt      # ESP-IDF MQTT client
  - json      # JSON parsing library

Installation Steps

  1. Add this component to your ESP-IDF project
  2. Add dependencies in CMakeLists.txt
  3. Configure MQTT Broker connection parameters

Quick Start

Basic Usage Example

#include "mcp_server.h"

// Define MCP tools
mcp_tool_t my_tools[] = {
    {
        .name = "get_temperature",
        .description = "Get device temperature",
        .property_count = 0,
        .properties = NULL,
        .call = get_temperature_callback
    }
};

// Initialize MCP server
mcp_server_t *server = mcp_server_init(
    "esp32_sensor",           // Server name
    "ESP32 Sensor MCP Server", // Description
    "mqtt://broker.example.com", // MQTT Broker URI
    "esp32_client_001",       // Client ID
    "username",               // Username
    "password",               // Password
    NULL                      // Certificate (optional)
);

// Register tools
mcp_server_register_tool(server, 1, my_tools);

// Start server
mcp_server_run(server);

Tool Callback Function Example

const char* get_temperature_callback(int n_args, property_t *args) {
    // Read sensor data
    float temp = read_temperature_sensor();
    
    // Return JSON formatted result
    static char result[64];
    snprintf(result, sizeof(result), "{\"temperature\": %.2f}", temp);
    return result;
}

Protocol Specification

This SDK implements the MCP over MQTT protocol specification, supporting:

  • Service Discovery: Automatic discovery and registration of MCP servers
  • Load Balancing: Support for multi-instance deployment
  • State Management: Maintain MCP server state
  • Access Control: Permission control based on MQTT topics

License

This project is licensed under the LICENSE license.