Servidor MCP en ESP32: Claude Code toma fotos
Ejecuta un servidor MCP en una ESP32-CAM y añádelo a Claude Code con un comando. Conoce take_snapshot, la guía /llms.txt y por qué debe quedarse en tu LAN.
- Autor
Mauro Brambilla- Publicado
- Tiempo de lectura
- 7 min
- Categoría
- Proyectos

En resumen
Gizmo Camera ejecuta un servidor MCP en la ESP32-CAM, en /mcp. Un solo comando claude mcp add --transport http le da a Claude Code la herramienta take_snapshot. No tiene login: déjala en tu LAN.
Un servidor MCP en ESP32 es un pequeño endpoint web en el microcontrolador que habla el Model Context Protocol, para que un agente de IA pueda llamar a las funciones del dispositivo como herramientas. En una ESP32-CAM, la herramienta es take_snapshot. Añade la cámara a Claude Code con claude mcp add --transport http gizmo-camera http://gizmo-camera.local/mcp y el agente podrá mirar la habitación.
¿Quieres que tu agente de programación revise la impresora 3D, la planta o la puerta sin que tengas que describírselas? Este artículo explica cómo funciona el servidor MCP de Gizmo Camera, cómo conectarlo y dónde están sus límites. Todo sale del código fuente y del README del proyecto, y de la documentación de Claude Code y de MCP enlazada en el texto. Cubre solo Claude Code, porque es el cliente cuyo comando pude comprobar en su documentación.
Cámara Wi-Fi con ESP32-CAM que saca una foto JPEG por petición, con una app web para configurarla desde el teléfono y un servidor MCP para agentes de IA.
- Fotos JPEG de hasta 1600 × 1200
- API HTTP sencilla
- Servidor MCP para agentes de IA
Una cosa antes de nada, porque afecta a lo que puedes flashear hoy. A 14 de noviembre de 2026, el servidor MCP está en la rama feature del repositorio gizmo-camera, y el firmware v1.0.0 publicado (el que flashea la web) se etiquetó antes de que se añadiera. Para usarlo ahora, compila el firmware desde el código fuente o prueba la opción sin hardware que se describe más abajo.
¿Qué significa darle una cámara a un agente de IA?
MCP (Model Context Protocol) es, según sus propias palabras, un estándar de código abierto para conectar aplicaciones de IA con sistemas externos. Un servidor enumera herramientas con un nombre y un esquema de entrada, y el agente decide cuándo llamarlas. La cámara es uno de esos sistemas: el agente pregunta, el ESP32 toma un JPEG nuevo y la imagen vuelve dentro del resultado de la herramienta para que el modelo la vea.

No hay streaming. Cada llamada es una sola foto, tomada cuando se pide, unos cientos de milisegundos después según la propia descripción de la herramienta. Encaja bien con la ESP32-CAM y usa la misma captura que la URL de snapshot, que por defecto usa el tamaño más grande en lugar de SVGA.
¿Dónde debe ejecutarse el servidor MCP?
Hay tres sitios posibles. Gizmo Camera usa el primero, así que la comparación trata del diseño, no de benchmarks.
| Arquitectura | Dónde se ejecuta el servidor MCP | Qué necesitas además del ESP32 |
|---|---|---|
| En el dispositivo (Gizmo Camera) | En el ESP32, por HTTP en /mcp | Nada: el agente se conecta directamente a la cámara |
| Puente en el lado del host (un diseño habitual, no se usa aquí) | En una computadora que habla con el ESP32 por puerto serie o HTTP | Una computadora que se quede encendida y ejecute el puente |
| MCP sobre MQTT | En el ESP32, con MQTT como transporte | Un broker MQTT y un cliente en la nube |
La tercera fila es como la describe EMQX en su artículo sobre ESP32 y MCP sobre MQTT: un cliente MCP en la nube y un LLM hablan con el ESP32 a través del broker EMQX. Es útil cuando el dispositivo está detrás de un firewall y debe ser accesible desde cualquier lugar. Para una cámara en tu escritorio, el servidor HTTP en el propio dispositivo es más sencillo, y el precio es que solo pueden llegar a él las máquinas de la misma red.

¿Cómo funciona el servidor MCP de Gizmo Camera?
El endpoint es POST /mcp, con el transporte Streamable HTTP. La especificación del transporte MCP permite que un servidor responda con un flujo de eventos o con un único objeto JSON. La cámara siempre elige el objeto JSON, así que nunca mantiene un flujo abierto. Un GET o un DELETE en /mcp recibe 405, algo que la especificación permite a los servidores que no ofrecen flujo, como describe el README.
El firmware está en microcontroller/src/mcp/ del repositorio (mcp_protocol.cpp para el protocolo, agent_guide.cpp para la guía), y las librerías salen de los pines de platformio.ini: ESPAsyncWebServer 3.12.1, AsyncTCP 3.5.0 y ArduinoJson 7.2.2. El README dice que el servidor habla la revisión 2026-07-28 de MCP y las anteriores que empiezan con initialize (2025-11-25, 2025-06-18, 2025-03-26), que la mayoría de los clientes siguen usando. El código del protocolo no depende del hardware, así que tiene pruebas nativas que puedes ejecutar con pio test -e native.
¿Qué herramientas ofrece la cámara?
Dos herramientas, ambas marcadas como de solo lectura en sus anotaciones:
| Herramienta | Argumentos | Devuelve |
|---|---|---|
| take_snapshot | resolution (de QQVGA a UXGA, por defecto SVGA 800x600), quality (de 4 a 63, por defecto 10), flash (true o false) | Una línea de texto con el tamaño y el tiempo de captura, y luego el JPEG como imagen |
| get_camera_info | Ninguno | Sensor, resoluciones, rango de calidad, flash, versión del firmware, como contenido estructurado y como texto JSON |
La lista de resoluciones se corta en lo que puede hacer el sensor: el OV2640 llega como máximo a UXGA (1600 x 1200). Los valores incorrectos no rompen nada: una resolución desconocida o una calidad fuera del rango de 4 a 63 vuelve como un error de la herramienta con un mensaje legible, para que el agente pueda corregir su llamada. La cámara toma una foto a la vez; una llamada que llega mientras hay otra en curso recibe un error que le dice al agente que espere y vuelva a intentarlo.
El valor por defecto para los agentes es SVGA, y las propias instrucciones del servidor explican por qué: SVGA basta para entender una escena, mientras que UXGA es más lenta y cuesta más tokens. El README añade que la codificación base64 hace que la foto ocupe un tercio más en la red, lo que cuesta tiempo de Wi-Fi y no tokens, y que la palanca más importante es la resolución. Yo no he medido el coste en tokens.
¿Cómo la añades a Claude Code con un solo comando?
Necesitas la cámara con un firmware que incluya el servidor MCP, en la misma red que la computadora donde se ejecuta Claude Code. Entonces, según la documentación de MCP de Claude Code (leída en noviembre de 2026), la sintaxis para un servidor HTTP es claude mcp add --transport http <name> <url>:
claude mcp add --transport http gizmo-camera http://gizmo-camera.local/mcpclaude mcp listCon claude mcp list ves todos los servidores configurados, y dentro de una sesión de Claude Code el comando /mcp muestra el estado de cada uno. Por defecto el servidor se añade en el ámbito local, es decir, solo para este proyecto, y la documentación indica --scope user para todos tus proyectos y --scope project para un .mcp.json compartido. El comando solo guarda la configuración, así que un error en la URL aparece como una conexión fallida en claude mcp list o en /mcp, no al pulsar Enter.
Si gizmo-camera.local no se resuelve en tu computadora, usa en su lugar la dirección IP de la cámara en la URL. Los motivos están en la guía del nombre de host .local. La página de la cámara en la aplicación web también muestra la dirección y el comando exactos, construidos con la dirección que usó tu navegador.
Bien, ahora pide algo que necesite ojos: "Toma una foto y dime qué hay en el escritorio." Claude Code debería llamar a take_snapshot y describir la imagen. Si responde que el sensor no arrancó, es el error de la herramienta de la cámara, y la causa habitual es el cable plano, como explica la guía de la ESP32-CAM-MB.
¿Aún no tienes la placa? Usa el servidor de desarrollo
La aplicación web tiene un dispositivo simulado que responde como el firmware, con una imagen de prueba PNG en lugar de la foto. Desde webapp/ ejecuta npm run dev y luego añádelo:
claude mcp add --transport http gizmo-camera-dev http://localhost:3000/mcpEse es el comando del README. Prueba el flujo de trabajo de tu agente, no la cámara.
¿Qué hace /llms.txt por un agente?
La propuesta llms.txt sugiere que los sitios web añadan un archivo Markdown /llms.txt con contenido pensado para los LLM. La cámara lo hace para un dispositivo: GET /llms.txt devuelve una guía breve con la dirección MCP, las herramientas y sus argumentos, la API HTTP simple y algunos consejos. El texto de la guía está en agent_guide.cpp, y el firmware sustituye un marcador {host} por la dirección que usó el agente para llegar a la cámara, así que los comandos que contiene funcionan tal como están escritos.
La misma guía se devuelve en / a los clientes cuyo encabezado Accept lista text/markdown antes que text/html, y las páginas de la aplicación web la enlazan con un enlace rel="alternate" en Markdown. Los navegadores siguen recibiendo la aplicación web. Es útil para un agente que solo tiene una URL: puede leer primero la guía y luego elegir entre MCP y la petición simple a /api/capture.
¿Es seguro? Sin login, solo LAN
No, al menos no en el sentido de la autenticación. La cámara no tiene ninguna: la aplicación web, la API y el servidor MCP responden a cualquiera que pueda llegar hasta ellos. El README lo dice sin rodeos, y la guía para agentes también.

El firmware añade algo de protección. El endpoint MCP solo responde en el nombre o la dirección propios de la cámara y rechaza otros sitios web según Origin, lo que bloquea el DNS rebinding. La especificación MCP pide a los servidores que lo hagan, en su aviso de seguridad, y también dice que los servidores deberían implementar una autenticación adecuada. La cámara hace lo primero y no lo segundo. Una pestaña del navegador en otro sitio no puede usarla, pero un script en tu red sí.
Qué significa eso en la práctica:
- No redirijas el puerto de la cámara en tu router
- No pongas la cámara en una red de invitados compartida con gente en la que no confías
- No la apuntes a nada que no quieras que vea una visita conectada a tu Wi-Fi
Hay una segunda consecuencia. El README señala que los agentes en la nube, como los conectores añadidos en claude.ai, no pueden llegar a una cámara de tu red doméstica. Es el precio del diseño solo LAN, y para este proyecto lo considero el correcto.
Qué conviene recordar
Gizmo Camera es un servidor MCP que se ejecuta en una ESP32-CAM: POST /mcp, respuestas JSON, dos herramientas de solo lectura y una guía en Markdown en /llms.txt. En Claude Code basta un comando, claude mcp add --transport http gizmo-camera http://gizmo-camera.local/mcp, comprobado con la documentación actual. Los agentes reciben SVGA por defecto, y un argumento incorrecto vuelve como un error que pueden leer.
Los límites: la cámara no tiene autenticación, así que su sitio es una LAN de confianza. A 14 de noviembre de 2026, el servidor MCP no está en el firmware v1.0.0 publicado, y aquí solo se cubre Claude Code. Si la placa se reinicia mientras pruebas, la guía del brownout cubre las causas de alimentación más habituales. Para la ruta con HTTP simple, mira la guía de la URL de snapshot, y para toda la familia, ¿Qué es OpenGizmo?
Preguntas frecuentes
Encuentra respuestas rápidas a las preguntas más comunes sobre este tema.
Sí. La ESP32-CAM de Gizmo Camera responde ella misma a las peticiones MCP en /mcp mediante Streamable HTTP, con ESPAsyncWebServer y ArduinoJson. Cada respuesta es un JSON simple, sin flujos de eventos ni sesiones, así que un chip pequeño puede con ello sin broker y sin una computadora que haga de puente.
Autor
Mauro Brambilla¿Listo para montar tu propio gizmo?
Elige un proyecto open source con ESP32 y sigue su guía paso a paso, desde la lista de componentes y el cableado hasta el firmware y el primer arranque.






