Server MCP su ESP32: Claude Code scatta le foto

Fai girare un server MCP su una ESP32-CAM e aggiungilo a Claude Code con un comando. Scopri il tool take_snapshot, la guida /llms.txt e perché resta nella LAN.

Pubblicato
Tempo di lettura
7 min
Categoria
Build
Un uomo con la barba e una maglia verde acqua scrive su un portatile che mostra un fumetto con una fotocamera, mentre una piccola camera su un supporto inquadra una pianta, accanto alla scritta MCP.

In breve

Gizmo Camera ospita un server MCP sulla ESP32-CAM, su /mcp. Un solo comando claude mcp add --transport http dà a Claude Code il tool take_snapshot. Non ha login: tienila nella LAN.

Un server MCP su ESP32 è un piccolo endpoint web sul microcontrollore che parla il Model Context Protocol, così un agente AI può chiamare le funzioni del dispositivo come tool. Su una ESP32-CAM il tool è take_snapshot. Aggiungi la telecamera a Claude Code con claude mcp add --transport http gizmo-camera http://gizmo-camera.local/mcp e l'agente può guardare la stanza.

Vuoi che il tuo agente di programmazione controlli la stampante 3D, la pianta o la porta senza che tu debba descrivergliele? Questo articolo spiega come funziona il server MCP di Gizmo Camera, come collegarlo e dove sono i suoi limiti. Tutto arriva dal codice sorgente e dal README del progetto e dalla documentazione di Claude Code e di MCP linkata nel testo. Copre solo Claude Code, perché è l'unico client di cui ho potuto verificare il comando sulla documentazione.

Progetto open-source ESP32-CAM
Gizmo Camera

Una fotocamera Wi-Fi con ESP32-CAM che scatta una foto JPEG a ogni richiesta, con una web app per configurarla dal telefono e un server MCP per gli agenti AI.

  • Foto JPEG fino a 1600 × 1200
  • API HTTP semplice
  • Server MCP per agenti AI
Dagli un'occhiata

Una cosa prima di tutto, perché cambia cosa puoi flashare oggi. Al 14 novembre 2026 il server MCP è sul branch feature del repository gizmo-camera, mentre il firmware v1.0.0 rilasciato (quello che flasha il sito web) è stato taggato prima che venisse aggiunto. Per usarlo adesso devi compilare il firmware dal sorgente oppure provare l'opzione senza hardware descritta più sotto.

Cosa significa dare una telecamera a un agente AI?

MCP (Model Context Protocol) è, nelle sue parole, uno standard open source per collegare le applicazioni AI a sistemi esterni. Un server elenca dei tool, ciascuno con un nome e uno schema degli input, e l'agente decide quando chiamarli. La telecamera è uno di questi sistemi: l'agente chiede, l'ESP32 scatta un nuovo JPEG e l'immagine torna dentro il risultato del tool, pronta perché il modello la guardi.

Un maker scrive al laptop mentre una ESP32-CAM su un supporto guarda una pianta, e un fumetto con la scritta MCP riporta indietro la foto

Non c'è nessuno streaming. Ogni chiamata è una sola foto, scattata quando viene richiesta, qualche centinaio di millisecondi dopo secondo la descrizione del tool stesso. Si sposa bene con la ESP32-CAM e usa la stessa acquisizione dell'URL per lo snapshot, che però di default usa la dimensione più grande invece di SVGA.

Dove deve girare il server MCP?

I posti possibili sono tre. Gizmo Camera usa il primo, quindi il confronto riguarda il design, non i benchmark.

ArchitetturaDove gira il server MCPCosa serve oltre all'ESP32
Sul dispositivo (Gizmo Camera)Sull'ESP32, in HTTP su /mcpNiente: l'agente si collega direttamente alla telecamera
Bridge lato host (un design comune, non usato qui)Su un computer che parla con l'ESP32 via seriale o HTTPUn computer che resta acceso e fa girare il bridge
MCP su MQTTSull'ESP32, con MQTT come trasportoUn broker MQTT e un client lato cloud

La terza riga è come la descrive EMQX nel suo articolo su ESP32 e MCP su MQTT: un client MCP lato cloud e un LLM parlano con l'ESP32 attraverso il broker EMQX. Va bene quando il dispositivo sta dietro un firewall e deve essere raggiungibile da ovunque. Per una telecamera sulla scrivania è più semplice il server HTTP sul dispositivo, e il prezzo da pagare è che la raggiungono solo le macchine della stessa rete.

L'agente invia un POST a /mcp con take_snapshot e la ESP32-CAM risponde con un JPEG in base64, senza broker né cloud in mezzo

Come funziona il server MCP di Gizmo Camera?

L'endpoint è POST /mcp e usa il trasporto Streamable HTTP. La specifica del trasporto MCP permette a un server di rispondere con uno stream di eventi oppure con un solo oggetto JSON. La telecamera sceglie sempre l'oggetto JSON, quindi non tiene mai uno stream aperto. Un GET o un DELETE su /mcp riceve 405, che la specifica consente ai server che non offrono uno stream, come descrive il README.

Il firmware sta in microcontroller/src/mcp/ del repository (mcp_protocol.cpp per il protocollo, agent_guide.cpp per la guida), e le librerie arrivano dai pin in platformio.ini: ESPAsyncWebServer 3.12.1, AsyncTCP 3.5.0 e ArduinoJson 7.2.2. Il README dice che il server parla la revisione 2026-07-28 di MCP e quelle precedenti che si aprono con initialize (2025-11-25, 2025-06-18, 2025-03-26), che la maggior parte dei client usa ancora. Il codice del protocollo non dipende dall'hardware, quindi ha dei test nativi che puoi lanciare con pio test -e native.

Che tool offre la telecamera?

Due tool, entrambi marcati come sola lettura nelle loro annotazioni:

ToolArgomentiRestituisce
take_snapshotresolution (da QQVGA a UXGA, default SVGA 800x600), quality (da 4 a 63, default 10), flash (true o false)Una riga di testo con dimensione e tempo di acquisizione, poi il JPEG come immagine
get_camera_infoNessunoSensore, risoluzioni, intervallo di qualità, flash, versione del firmware, come contenuto strutturato e come testo JSON

L'elenco delle risoluzioni si ferma a quello che sa fare il sensore: l'OV2640 arriva al massimo a UXGA (1600 x 1200). I valori sbagliati non fanno crashare niente: una risoluzione sconosciuta o una qualità fuori dall'intervallo da 4 a 63 torna come errore del tool con un messaggio leggibile, così l'agente può correggere la chiamata. La telecamera scatta una foto alla volta; una chiamata che arriva mentre ne è in corso un'altra riceve un errore che dice all'agente di aspettare e riprovare.

Il default per gli agenti è SVGA, e le istruzioni del server stesso spiegano perché: SVGA basta per capire una scena, mentre UXGA è più lenta e costa più token. Il README aggiunge che la codifica base64 rende la foto più grande di circa un terzo in rete, il che costa tempo di Wi-Fi e non token, e che la leva più importante è la risoluzione. Non ho misurato io stesso il costo in token.

Come lo aggiungi a Claude Code con un solo comando?

Ti serve la telecamera con un firmware che includa il server MCP, nella stessa rete del computer dove gira Claude Code. A quel punto, secondo la documentazione MCP di Claude Code (letta a novembre 2026), la sintassi per un server HTTP è claude mcp add --transport http <name> <url>:

Aggiungi la telecamera a Claude Code
claude mcp add --transport http gizmo-camera http://gizmo-camera.local/mcpclaude mcp list

Con claude mcp list vedi tutti i server configurati, e dentro una sessione di Claude Code il comando /mcp mostra lo stato di ciascuno. Di default il server viene aggiunto nello scope local, cioè solo per questo progetto, e la documentazione elenca --scope user per tutti i tuoi progetti e --scope project per un .mcp.json condiviso. Il comando salva soltanto la configurazione, quindi un errore nell'URL si vede come connessione fallita in claude mcp list o in /mcp, non quando premi Invio.

Se gizmo-camera.local non si risolve sul tuo computer, usa invece l'indirizzo IP della telecamera nell'URL. I motivi sono nella guida all'hostname .local. Anche la pagina della telecamera nella web app mostra l'indirizzo e il comando esatti, costruiti con l'indirizzo che ha usato il tuo browser.

Bene, ora chiedi qualcosa che richiede degli occhi: "Scatta una foto e dimmi cosa c'è sulla scrivania." Claude Code dovrebbe chiamare take_snapshot e descrivere l'immagine. Se risponde che il sensore non è partito, è l'errore del tool della telecamera, e di solito la causa è il cavo flat, come spiega la guida alla ESP32-CAM-MB.

Non hai ancora la scheda? Usa il dev server

La web app ha un dispositivo finto che risponde come il firmware, con un'immagine di prova PNG al posto della foto. Da webapp/ lancia npm run dev, poi aggiungilo:

Prova il server MCP senza hardware
claude mcp add --transport http gizmo-camera-dev http://localhost:3000/mcp

Questo è il comando del README. Mette alla prova il flusso di lavoro del tuo agente, non la telecamera.

A cosa serve /llms.txt a un agente?

La proposta llms.txt suggerisce ai siti web di aggiungere un file Markdown /llms.txt con contenuti adatti agli LLM. La telecamera lo fa per un dispositivo: GET /llms.txt restituisce una breve guida con l'indirizzo MCP, i tool e i loro argomenti, la semplice API HTTP e qualche consiglio. Il testo della guida sta in agent_guide.cpp, e il firmware sostituisce un segnaposto {host} con l'indirizzo che l'agente ha usato per raggiungere la telecamera, così i comandi al suo interno funzionano così come sono scritti.

La stessa guida viene restituita su / ai client il cui header Accept elenca text/markdown prima di text/html, e le pagine della web app la linkano con un link rel="alternate" in Markdown. I browser ricevono comunque la web app. Torna utile a un agente che ha solo un URL: può leggere prima la guida, poi scegliere tra MCP e la semplice richiesta /api/capture.

È sicuro? Niente login, solo LAN

No, non nel senso dell'autenticazione. La telecamera non ne ha: la web app, l'API e il server MCP rispondono a chiunque riesca a raggiungerli. Lo dice chiaramente il README, e lo dice anche la guida per gli agenti.

A sinistra: stessa rete, Claude Code sul tuo computer con gizmo-camera.local o l'IP. A destra: mai port forwarding verso internet né agenti cloud su claude.ai

Il firmware aggiunge qualche protezione. L'endpoint MCP risponde solo sul nome o sull'indirizzo della telecamera e rifiuta gli altri siti web in base a Origin, il che blocca il DNS rebinding. La specifica MCP chiede ai server di farlo, nel suo avviso di sicurezza, e dice anche che i server dovrebbero implementare un'autenticazione adeguata. La telecamera fa la prima cosa e non la seconda. Una scheda del browser su un altro sito non può usarla, ma uno script nella tua rete sì.

Cosa significa in pratica:

  • Non inoltrare la porta della telecamera sul router
  • Non mettere la telecamera su una rete ospiti condivisa con persone di cui non ti fidi
  • Non puntarla su niente che non vorresti far vedere a un ospite collegato al tuo Wi-Fi

C'è una seconda conseguenza. Il README osserva che gli agenti nel cloud, come i connettori aggiunti su claude.ai, non raggiungono una telecamera nella tua rete di casa. È il prezzo del design solo LAN, e per questo progetto lo considero quello giusto.

Cosa portarti a casa

Gizmo Camera è un server MCP che gira su una ESP32-CAM: POST /mcp, risposte JSON, due tool in sola lettura e una guida in Markdown su /llms.txt. In Claude Code basta un comando, claude mcp add --transport http gizmo-camera http://gizmo-camera.local/mcp, verificato sulla documentazione attuale. Gli agenti ricevono SVGA di default, e un argomento sbagliato torna come errore che possono leggere.

I limiti: la telecamera non ha autenticazione, quindi il suo posto è una LAN fidata. Al 14 novembre 2026 il server MCP non è nel firmware v1.0.0 rilasciato, e qui è coperto solo Claude Code. Se la scheda si resetta mentre provi, la guida al brownout copre le cause di alimentazione più comuni. Per la strada con il semplice HTTP c'è la guida all'URL per lo snapshot, e per tutta la famiglia Cos'è OpenGizmo?

Domande frequenti

Trova risposte rapide alle domande più comuni su questo argomento.

Sì. La ESP32-CAM di Gizmo Camera risponde da sola alle richieste MCP su /mcp con Streamable HTTP, usando ESPAsyncWebServer e ArduinoJson. Ogni risposta è un semplice JSON, senza stream di eventi né sessioni, quindi un chip piccolo se la cava senza broker e senza un computer che faccia da ponte.

Pubblicato

Pronto a costruire il tuo gizmo?

Scegli un progetto ESP32 open source e segui la sua guida passo passo, dalla lista dei componenti e dai collegamenti fino al firmware e al primo avvio.

Leggi anche

Esplora le categorie