Mcpesp
ESP32 MCP server library
Ask AI about Mcpesp
Powered by Claude · Grounded in docs
I know everything about Mcpesp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Mcpesp - ESP32 Model Context Protocol Library
A configurable Arduino library for implementing Model Context Protocol (MCP) servers on ESP32 devices. This library enables you to expose ESP32 hardware capabilities as MCP tools that can be called via HTTP/JSON-RPC, allowing AI models and other clients to interact with your ESP32 through a standardized protocol.
Description
Mcpesp provides a complete implementation of the Model Context Protocol server for ESP32. It handles JSON-RPC requests, tool registration, schema validation, and CORS headers, making it easy to create MCP servers that expose ESP32 functionality to external clients.
Features
- MCP Protocol Support: Basic implementation of MCP protocol
- Tool Registration: Easily register custom tools with callback functions
- Schema Validation: Built-in schema builder for defining tool input parameters
- HTTP Server: Integrates into the ESP32's WebServer for handling HTTP/JSON-RPC requests
- JSON-RPC 2.0: Compatible with JSON-RPC 2.0 specification
- WiFi Integration: Works with ESP32 WiFi capabilities
Installation
Arduino IDE
- Download or clone this repository
- Place the
mcpespfolder in your Arduinolibrariesdirectory - Restart the Arduino IDE
PlatformIO
Add to your platformio.ini:
lib_deps =
bblanchon/ArduinoJson@^7.0.0
Dependencies
- ArduinoJson: JSON parsing and generation library (version 7.x or compatible)
- ESP32 Board Support: Requires ESP32 board support package for Arduino IDE
- WebServer: Included with ESP32 core libraries
Quick Start
#include <WiFi.h>
#include <mcpesp.h>
// WiFi credentials
const char* ssid = "YOUR_WIFI_SSID";
const char* password = "YOUR_WIFI_PASSWORD";
// LED pin for demonstration
#define LED_PIN 8
// Create MCP server instance
Mcpesp mcpServer;
void myToolCallback(JsonObject arguments, JsonObject result) {
bool state = arguments["enabled"].as<bool>(); // Name of the property is "enabled"
bool ledState = state;
digitalWrite(LED_PIN, ledState ? LOW : HIGH); // LOW = ON for most ESP32 boards
result["text"] = "LED turned " + String(state) + " successfully!";
Serial.println("LED state changed to: " + state);
}
void setup() {
Serial.begin(115200);
// Connect to WiFi
WiFi.begin(ssid, password);
while (WiFi.status() != WL_CONNECTED) {
delay(500);
Serial.print(".");
}
Serial.println("\nConnected!");
// Initialize MCP server
mcpServer.begin("My MCP Server", "1.0.0");
// Create tool schema
Schema toolSchema;
toolSchema.addBooleanProperty("enabled", "Enable or disable feature");
// Register tool
mcpServer.addTool(
"my_tool",
"Description of my tool",
toolSchema,
myToolCallback
);
}
void loop() {
mcpServer.handleClient();
}
API Reference
Mcpesp Class
Constructor
Mcpesp()
Creates a new MCP server instance.
Methods
begin(serverName, version, port)
Initializes the MCP server.
- Parameters:
serverName(const char*): Name of the server (default: "ESP32 MCP Server")version(const char*): Server version (default: "1.0.0")port(int): HTTP server port (default: 80)
- Returns: void
addTool(name, description, inputSchema, callback)
Registers a new tool with the server.
- Parameters:
name(const String&): Tool name (must be unique)description(const String&): Tool descriptioninputSchema(Schema&): Input parameter schemacallback(toolCallback): Callback function to execute when tool is called
- Returns: void
handleClient()
Handles incoming client requests. Call this in your loop() function.
- Returns: void
setServerInfo(name, version)
Updates server name and version.
- Parameters:
name(const String&): Server nameversion(const String&): Server version
- Returns: void
setProtocolVersion(version)
Sets the MCP protocol version.
- Parameters:
version(const String&): Protocol version (default: "2025-03-26")
- Returns: void
isInitialized()
Checks if the server is initialized.
- Returns: bool
getServer()
Gets the underlying WebServer instance for advanced usage.
- Returns: WebServer*
Schema Class
The Schema class is used to define input parameter schemas for tools.
Constructor
Schema()
Creates a new schema instance.
Methods
addStringProperty(name, description, required)
Adds a string property to the schema.
- Parameters:
name(String): Property namedescription(String): Property descriptionrequired(bool): Whether the property is required (default: true)
- Returns: void
addStringEnumProperty(name, description, options, required)
Adds a string enum property to the schema.
- Parameters:
name(String): Property namedescription(String): Property descriptionoptions(String[]): Array of allowed valuesrequired(bool): Whether the property is required (default: true)
- Returns: void
addNumberProperty(name, description, required)
Adds a number property to the schema.
- Parameters:
name(String): Property namedescription(String): Property descriptionrequired(bool): Whether the property is required (default: true)
- Returns: void
addNumberProperty(name, description, min, max, def, required)
Adds a number property with constraints to the schema.
- Parameters:
name(String): Property namedescription(String): Property descriptionmin(int): Minimum valuemax(int): Maximum valuedef(int): Default valuerequired(bool): Whether the property is required (default: true)
- Returns: void
addBooleanProperty(name, description, required)
Adds a boolean property to the schema.
- Parameters:
name(String): Property namedescription(String): Property descriptionrequired(bool): Whether the property is required (default: true)
- Returns: void
getSchema()
Returns the JSON schema document.
- Returns: JsonDocument
Tool Callback Function
Tool callbacks have the following signature:
void toolCallback(JsonObject arguments, JsonObject result)
- Parameters:
arguments(JsonObject): Input parameters from the clientresult(JsonObject): Result object to populate (setresult["text"]for the response)
- Returns: void
Examples
See the examples/McpServerExample/ directory for a complete example demonstrating:
- WiFi connection
- Server initialization
- Tool registration with different schema types
- Tool callback implementation
MCP Protocol
This library implements the following MCP methods:
initialize: Initializes the MCP connectiontools/list: Lists all registered toolstools/call: Calls a registered tool
All methods follow the JSON-RPC 2.0 specification and return appropriate responses.
License
This library is based on the work from https://github.com/MrLaki5/ESP32-MCP-air-conditioner
Contributing
Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.
Support
For any bug reports or feature requests, please open an issue on the repository.
