ESP32 MCP-Server: Claude Code macht Fotos
Betreibe einen MCP-Server auf der ESP32-CAM und füge ihn Claude Code per Befehl hinzu. Das Tool take_snapshot, der /llms.txt-Guide und warum er im LAN bleibt.
- Autor
Mauro Brambilla- Veroffentlicht
- Lesezeit
- 7 Min.
- Kategorie
- Projekte

Kurz gesagt
Gizmo Camera betreibt einen MCP-Server auf der ESP32-CAM unter /mcp. Ein einziger Befehl claude mcp add --transport http gibt Claude Code das Tool take_snapshot. Es gibt keinen Login: im LAN lassen.
Ein ESP32 MCP-Server ist ein kleiner Web-Endpunkt auf dem Mikrocontroller, der das Model Context Protocol spricht, sodass ein KI-Agent die Funktionen des Geräts als Tools aufrufen kann. Auf einer ESP32-CAM heißt das Tool take_snapshot. Füge die Kamera mit claude mcp add --transport http gizmo-camera http://gizmo-camera.local/mcp zu Claude Code hinzu, und der Agent kann sich im Raum umsehen.
Soll dein Coding-Agent den 3D-Drucker, die Pflanze oder die Tür prüfen, ohne dass du sie ihm beschreiben musst? Dieser Beitrag zeigt, wie der MCP-Server von Gizmo Camera funktioniert, wie du ihn verbindest und wo seine Grenzen liegen. Alles stammt aus dem Quellcode und der README des Projekts sowie aus der Dokumentation von Claude Code und MCP, die im Text verlinkt ist. Es geht nur um Claude Code, weil das der einzige Client ist, dessen Befehl ich an der Dokumentation prüfen konnte.
WLAN-Kamera mit ESP32-CAM, die bei jeder Anfrage ein JPEG-Foto macht, mit Web-App für die Einrichtung per Smartphone und einem MCP-Server für KI-Agenten.
- JPEG-Fotos bis 1600 × 1200
- Einfache HTTP-API
- MCP-Server für KI-Agenten
Vorab etwas, das beeinflusst, was du heute flashen kannst. Stand 14. November 2026 liegt der MCP-Server auf dem Branch feature des gizmo-camera-Repositorys, und die veröffentlichte Firmware v1.0.0 (die, die die Website flasht) wurde getaggt, bevor er dazukam. Um ihn jetzt zu nutzen, baust du die Firmware aus dem Quellcode oder probierst die weiter unten beschriebene Variante ohne Hardware.
Was heißt es, einem KI-Agenten eine Kamera zu geben?
MCP (Model Context Protocol) ist laut eigener Beschreibung ein Open-Source-Standard, um KI-Anwendungen mit externen Systemen zu verbinden. Ein Server listet Tools mit Namen und Eingabeschema auf, und der Agent entscheidet, wann er sie aufruft. Die Kamera ist so ein System: Der Agent fragt, der ESP32 nimmt ein neues JPEG auf, und das Bild kommt im Tool-Ergebnis zurück, damit das Modell es ansehen kann.

Es wird nichts gestreamt. Jeder Aufruf ist ein einzelnes Foto, aufgenommen, wenn es angefordert wird, laut Beschreibung des Tools wenige hundert Millisekunden später. Das passt gut zur ESP32-CAM und nutzt dieselbe Aufnahme wie die Snapshot-URL, die standardmäßig die größte Auflösung statt SVGA verwendet.
Wo sollte der MCP-Server laufen?
Es gibt drei Möglichkeiten. Gizmo Camera nimmt die erste, der Vergleich betrifft also das Design, nicht Benchmarks.
| Architektur | Wo der MCP-Server läuft | Was du außer dem ESP32 brauchst |
|---|---|---|
| Auf dem Gerät (Gizmo Camera) | Auf dem ESP32, per HTTP unter /mcp | Nichts: Der Agent verbindet sich direkt mit der Kamera |
| Bridge auf der Host-Seite (ein gängiges Design, hier nicht genutzt) | Auf einem Rechner, der über die serielle Schnittstelle oder HTTP mit dem ESP32 spricht | Ein Rechner, der anbleibt und die Bridge ausführt |
| MCP über MQTT | Auf dem ESP32, mit MQTT als Transport | Ein MQTT-Broker und ein Client in der Cloud |
Die dritte Zeile beschreibt EMQX in seinem Artikel zu ESP32 und MCP über MQTT so: Ein MCP-Client in der Cloud und ein LLM sprechen über den EMQX-Broker mit dem ESP32. Das ist praktisch, wenn das Gerät hinter einer Firewall sitzt und von überall erreichbar sein muss. Für eine Kamera auf deinem Schreibtisch ist der HTTP-Server auf dem Gerät einfacher, und der Preis ist, dass nur Rechner im selben Netz ihn erreichen.

Wie funktioniert der MCP-Server von Gizmo Camera?
Der Endpunkt ist POST /mcp und nutzt den Transport Streamable HTTP. Die MCP-Transportspezifikation erlaubt einem Server, entweder mit einem Event-Stream oder mit einem einzelnen JSON-Objekt zu antworten. Die Kamera wählt immer das JSON-Objekt und hält deshalb nie einen Stream offen. Ein GET oder DELETE auf /mcp bekommt 405, was die Spezifikation für Server erlaubt, die keinen Stream anbieten, wie die README beschreibt.
Die Firmware liegt im Repository unter microcontroller/src/mcp/ (mcp_protocol.cpp für das Protokoll, agent_guide.cpp für den Guide), und die Bibliotheken kommen aus den Pins in platformio.ini: ESPAsyncWebServer 3.12.1, AsyncTCP 3.5.0 und ArduinoJson 7.2.2. Laut README spricht der Server die MCP-Revision 2026-07-28 und die früheren, die mit initialize beginnen (2025-11-25, 2025-06-18, 2025-03-26), die die meisten Clients noch verwenden. Der Protokollcode kommt ohne Hardware aus, deshalb gibt es native Tests, die du mit pio test -e native ausführen kannst.
Welche Tools bietet die Kamera?
Zwei Tools, beide in ihren Annotationen als schreibgeschützt markiert:
| Tool | Argumente | Rückgabe |
|---|---|---|
| take_snapshot | resolution (QQVGA bis UXGA, Standard SVGA 800x600), quality (4 bis 63, Standard 10), flash (true oder false) | Eine Textzeile mit Größe und Aufnahmezeit, dann das JPEG als Bild |
| get_camera_info | Keine | Sensor, Auflösungen, Qualitätsbereich, Blitz, Firmware-Version, als strukturierter Inhalt und als JSON-Text |
Die Liste der Auflösungen endet bei dem, was der Sensor kann: Der OV2640 schafft höchstens UXGA (1600 x 1200). Falsche Werte lassen nichts abstürzen: Eine unbekannte Auflösung oder eine Qualität außerhalb von 4 bis 63 kommt als Tool-Fehler mit lesbarer Meldung zurück, sodass der Agent seinen Aufruf korrigieren kann. Die Kamera macht jeweils nur ein Foto; ein Aufruf, der während eines anderen eintrifft, bekommt einen Fehler, der dem Agenten sagt, er soll warten und es erneut versuchen.
Der Standard für Agenten ist SVGA, und die Anweisungen des Servers selbst nennen den Grund: SVGA reicht, um eine Szene zu verstehen, während UXGA langsamer ist und mehr Tokens kostet. Die README ergänzt, dass die Base64-Kodierung das Foto auf der Leitung um etwa ein Drittel größer macht, was WLAN-Zeit kostet und keine Tokens, und dass der größere Hebel die Auflösung ist. Die Token-Kosten habe ich nicht selbst gemessen.
Wie fügst du ihn mit einem Befehl zu Claude Code hinzu?
Du brauchst die Kamera mit einer Firmware, die den MCP-Server enthält, im selben Netz wie der Rechner, auf dem Claude Code läuft. Dann lautet die Syntax für einen HTTP-Server laut MCP-Dokumentation von Claude Code (gelesen im November 2026) claude mcp add --transport http <name> <url>:
claude mcp add --transport http gizmo-camera http://gizmo-camera.local/mcpclaude mcp listclaude mcp list listet alle konfigurierten Server auf, und in einer Claude-Code-Sitzung zeigt der Befehl /mcp den Status jedes Servers. Standardmäßig wird der Server im Scope local hinzugefügt, also nur für dieses Projekt, und die Dokumentation nennt --scope user für alle deine Projekte und --scope project für eine gemeinsame .mcp.json. Der Befehl speichert nur die Konfiguration, ein Tippfehler in der URL zeigt sich also als fehlgeschlagene Verbindung in claude mcp list oder /mcp, nicht beim Drücken von Enter.
Wenn sich gizmo-camera.local auf deinem Rechner nicht auflösen lässt, nimm stattdessen die IP-Adresse der Kamera in der URL. Die Gründe stehen in der Anleitung zum .local-Hostnamen. Auch die Kameraseite der Web-App zeigt die genaue Adresse und den Befehl, gebaut aus der Adresse, die dein Browser benutzt hat.
So, jetzt frag etwas, wofür man Augen braucht: „Mach ein Foto und sag mir, was auf dem Schreibtisch liegt.“ Claude Code sollte take_snapshot aufrufen und das Bild beschreiben. Antwortet es, dass der Sensor nicht gestartet ist, ist das der Tool-Fehler der Kamera, und die übliche Ursache ist das Flachbandkabel, wie die Anleitung zum ESP32-CAM-MB erklärt.
Noch kein Board? Nimm den Dev-Server
Die Web-App hat ein Mock-Gerät, das wie die Firmware antwortet, mit einem PNG-Testbild statt des Fotos. Starte in webapp/ npm run dev und füge es dann hinzu:
claude mcp add --transport http gizmo-camera-dev http://localhost:3000/mcpDas ist der Befehl aus der README. Er testet den Ablauf deines Agenten, nicht die Kamera.
Was bringt /llms.txt einem Agenten?
Der llms.txt-Vorschlag regt an, dass Websites eine Markdown-Datei /llms.txt mit LLM-freundlichen Inhalten anbieten. Die Kamera macht das für ein Gerät: GET /llms.txt liefert einen kurzen Guide mit der MCP-Adresse, den Tools und ihren Argumenten, der einfachen HTTP-API und ein paar Tipps. Der Text des Guides steht in agent_guide.cpp, und die Firmware ersetzt einen Platzhalter {host} durch die Adresse, über die der Agent die Kamera erreicht hat, sodass die Befehle darin genau so funktionieren, wie sie dastehen.
Derselbe Guide kommt unter / für Clients, deren Accept-Header text/markdown vor text/html auflistet, und die Seiten der Web-App verlinken ihn mit einem Markdown-Link per rel="alternate". Browser bekommen weiterhin die Web-App. Das hilft einem Agenten, der nur eine URL hat: Er kann zuerst den Guide lesen und sich dann zwischen MCP und der einfachen Anfrage an /api/capture entscheiden.
Ist das sicher? Kein Login, nur LAN
Nein, jedenfalls nicht im Sinne einer Authentifizierung. Die Kamera hat keine: Die Web-App, die API und der MCP-Server antworten jedem, der sie erreichen kann. Die README sagt das klar, und der Agenten-Guide auch.

Die Firmware bringt etwas Schutz mit. Der MCP-Endpunkt antwortet nur auf den eigenen Namen oder die eigene Adresse der Kamera und weist andere Websites anhand von Origin ab, was DNS-Rebinding blockiert. Die MCP-Spezifikation verlangt das von Servern in ihrem Sicherheitshinweis und sagt außerdem, dass Server eine ordentliche Authentifizierung umsetzen sollten. Die Kamera macht das Erste und nicht das Zweite. Ein Browser-Tab auf einer anderen Website kann sie nicht nutzen, ein Skript in deinem Netz schon.
Was das in der Praxis heißt:
- Gib den Port der Kamera nicht am Router frei
- Stell die Kamera nicht in ein Gastnetz, das du mit Leuten teilst, denen du nicht traust
- Richte sie auf nichts, was ein Besucher in deinem WLAN nicht sehen sollte
Es gibt eine zweite Folge. Die README merkt an, dass Agenten in der Cloud, etwa Konnektoren, die du auf claude.ai hinzufügst, eine Kamera in deinem Heimnetz nicht erreichen. Das ist der Preis des reinen LAN-Designs, und für dieses Projekt halte ich ihn für richtig.
Was du mitnehmen solltest
Gizmo Camera ist ein MCP-Server, der auf einer ESP32-CAM läuft: POST /mcp, JSON-Antworten, zwei schreibgeschützte Tools und ein Markdown-Guide unter /llms.txt. In Claude Code genügt ein Befehl, claude mcp add --transport http gizmo-camera http://gizmo-camera.local/mcp, geprüft an der aktuellen Dokumentation. Agenten bekommen standardmäßig SVGA, und ein falsches Argument kommt als Fehler zurück, den sie lesen können.
Die Grenzen: Die Kamera hat keine Authentifizierung, ihr Platz ist also ein vertrauenswürdiges LAN. Stand 14. November 2026 ist der MCP-Server nicht in der veröffentlichten Firmware v1.0.0, und hier geht es nur um Claude Code. Wenn das Board beim Testen neu startet, behandelt die Anleitung zum Brownout die üblichen Stromversorgungsursachen. Für den Weg über einfaches HTTP siehe die Anleitung zur Snapshot-URL, und für die ganze Familie Was ist OpenGizmo?
Haufig gestellte Fragen
Finden Sie schnelle Antworten auf die haufigsten Fragen zu diesem Thema.
Ja. Die ESP32-CAM in Gizmo Camera beantwortet MCP-Anfragen selbst unter /mcp per Streamable HTTP, mit ESPAsyncWebServer und ArduinoJson. Jede Antwort ist schlichtes JSON, ohne Event-Streams und ohne Sessions, deshalb schafft das ein kleiner Chip ohne Broker und ohne Rechner als Brücke.
Autor
Mauro BrambillaLust, dein eigenes Gizmo zu bauen?
Such dir ein Open-Source-Projekt mit dem ESP32 aus und folge der Schritt-für-Schritt-Anleitung, von der Teileliste und der Verkabelung bis zur Firmware und zum ersten Start.





