Gemini MCP

Integra resultados de Gemini basados en búsqueda en tu flujo de trabajo.

Documentación

Gemini MCP - Generación de imágenes, video y búsqueda con grounding de Google Gemini dentro de Claude

He tenido este servidor MCP de Gemini funcionando en mi configuración de Claude Desktop durante casi un año. Es uno de los pocos que dejo encendido permanentemente. No porque Gemini reemplace a Claude (no lo hace), sino porque la búsqueda con grounding, la generación de imágenes, los diagramas SVG y el video son cosas que Gemini hace bien, y tenerlas como herramientas dentro de Claude es mejor que estar alternando entre pestañas del navegador.

Catorce herramientas, construidas alrededor de los modelos que la gente realmente busca: Nano Banana Pro (gemini-3-pro-image) y Nano Banana 2 para imágenes, Veo 3.1 para video con audio sincronizado, y Gemini 3.1 Pro para chat e investigación profunda con grounding en la Búsqueda de Google. Todo se previsualiza en línea dentro de Claude Desktop a través de MCP Apps, en lugar de terminar como una ruta de archivo que tienes que ir a abrir.

Un solo comando npx. Eso es todo.

Navegación rápida

Qué crea | Cómo empezar | Qué hace | Salida de imágenes | Configuración | Herramientas | Modelos | Requisitos

Qué crea

Todo lo que aparece a continuación salió de las herramientas de este repositorio, sin retoques, la tarde en que escribí esto. Los prompts están en los pies de foto para que puedas juzgar por ti mismo.

Generación de imágenes con grounding de búsqueda. Una llamada a generate_image con use_search=true. Gemini consultó el pronóstico real de la Met Office para la semana y luego lo dibujó. Las fechas y temperaturas son reales (bueno, tan reales como puede ser un pronóstico).

London five-day weather infographic, generated by Nano Banana Pro from live search data

Prompt: "Un póster infográfico editorial pulido: clima en Londres, esta semana. Usa datos reales del pronóstico de búsqueda para los próximos 5 días..." - gemini-3-pro-image, 16:9, 2K.

Texto que en realidad está bien escrito. Esto es lo que Nano Banana Pro hace que la generación anterior de modelos de imagen no podía. Cada etiqueta aquí sale directamente del modelo.

Four-step infographic explaining an MCP tool call, with correctly rendered text

Prompt: "Una infografía limpia, con calidad de revista, titulada Cómo funciona una llamada a una herramienta MCP, con cuatro pasos numerados..." - gemini-3-pro-image.

Generar y luego editar. A la izquierda está generate_image. A la derecha está edit_image sobre ese archivo con una sola frase de instrucciones: cambia la pista a Monza a la luz del día, cambia la luz de contorno por luz de ventana, haz los pedales rojos. Misma cabina, mismo ángulo de cámara.

`generate_image`	`edit_image`

De imagen a video con Veo 3.1. La cabina nocturna de arriba, pasada a generate_video como firstFrameImage. Ocho segundos a 1080p con audio generado (sonido del motor, silbido de neumáticos): el GIF de abajo está en silencio y comprimido para GitHub; el archivo real es un MP4 de verdad.

Veo 3.1 video: the cockpit comes to life, hands turning the wheel through Eau Rouge

SVG que realmente puedes usar. No es una imagen de un diagrama: es marcado vectorial real que puedes insertar en una página, editar a mano o subir a un repositorio. Ambos son los archivos .svg crudos que la herramienta escribió en el disco.

`generate_svg` estilo=técnico	`generate_svg` estilo=visualización-de-datos

Una página de aterrizaje a partir de un párrafo. generate_landing_page con una breve descripción, un nombre de empresa y un color de marca. HTML autocontenido, CSS en línea, el pequeño gráfico en el héroe es SVG animado. Captura de pantalla del archivo abierto en Chrome, sin tocar nada más.

Generated SaaS landing page rendered in a browser

Y el rápido. Nano Banana 2 (gemini-3.1-flash-image) para cuando quieres volumen en lugar de 4K. Esto tomó unos diez segundos.

Flat-lay of a mechanical keyboard on a walnut desk, Nano Banana 2

Cómo empezar en dos minutos

Paso 1: Obtén una clave de API de Gemini

Ve a Google AI Studio y crea una.

Una nota sobre el nivel gratuito, porque los valores predeterminados dependen de un modelo de pago. La página de precios de Google (al 24 de septiembre de 2026) otorga a Gemini 3 Flash Preview un nivel gratuito, pero Gemini 3.1 Pro Preview es solo de pago, y 3.1 Pro es el predeterminado para gemini_chat, gemini_deep_research (síntesis), analyze_image y generate_landing_page. Con una clave gratuita, esas llamadas fallarán a menos que las apuntes a un modelo gratuito: establece GEMINI_DEFAULT_MODEL=gemini-3-flash-preview (cubre chat y páginas de aterrizaje), GEMINI_DEEP_RESEARCH_MODEL y GEMINI_IMAGE_ANALYSIS_MODEL de igual manera, o pasa model por llamada. generate_svg ya usa gemini-3-flash-preview por defecto. Consulta la página de precios para los otros modelos antes de depender de ellos: Google cambia estos niveles.

Paso 2: Agrégalo a tu configuración de Claude Desktop

Ubicaciones del archivo de configuración:

Windows: C:\Users\{username}\AppData\Roaming\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": ["@houtini/gemini-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Paso 3: Reinicia Claude Desktop

Eso es todo. Las herramientas aparecen automáticamente. npx descarga el paquete en la primera ejecución, así que no hay instalación por separado.

Compilación local en su lugar

Para desarrollo, o si prefieres no depender de npx:

git clone https://github.com/houtini-ai/gemini-mcp
cd gemini-mcp
npm install --include=dev
npm run build

Luego apunta tu configuración a la compilación local:

{
  "mcpServers": {
    "gemini": {
      "command": "node",
      "args": ["C:/path/to/gemini-mcp/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code (CLI)

Claude Code no lee claude_desktop_config.json. Usa claude mcp add en su lugar:

claude mcp add -e GEMINI_API_KEY=your-api-key-here -s user gemini -- npx -y @houtini/gemini-mcp

Con un directorio de salida para imágenes y video:

claude mcp add \
  -e GEMINI_API_KEY=your-api-key-here \
  -e GEMINI_IMAGE_OUTPUT_DIR=/path/to/output \
  -s user \
  gemini -- npx -y @houtini/gemini-mcp

Verifica con claude mcp get gemini: quieres ver Status: Connected.

Qué hace

Chat con grounding en la Búsqueda de Google

Use gemini:gemini_chat to ask: "What changed in the MCP spec in the last month?"

El grounding está activado por defecto. Gemini busca en Google antes de responder, así obtienes información de este mes en lugar de una suposición basada en la fecha de corte del entrenamiento, y las fuentes vuelven como enlaces de markdown. Para preguntas donde quieres razonamiento puro ("explica este código", ese tipo de cosas), establece grounding: false.

Se ejecuta en gemini-3.1-pro-preview a menos que indiques lo contrario. Pasa model: "gemini-3.8-flash" si prefieres velocidad en lugar de profundidad. thinking_level funciona en todos los modelos Gemini 3.x: high para lo difícil, low para mantenerlo ágil.

Investigación profunda

Use gemini:gemini_deep_research with:
  research_question="What are the current approaches to AI agent memory management?"
  max_iterations=5

Ejecuta pasadas de búsqueda con grounding y luego las redacta como un solo informe. Las pasadas se ejecutan en gemini-3.8-flash con pensamiento bajo (están recopilando hechos, no razonando sobre ellos), y la síntesis al final se ejecuta en gemini-3.1-pro-preview con pensamiento alto. Dos pasadas más una síntesis es el valor predeterminado y tarda de dos a tres minutos.

Esa división importa más de lo que parece. Las versiones anteriores ejecutaban todo en Pro con pensamiento completo, y una sola pasada sobre una pregunta amplia podía superar el tiempo de espera de cuatro minutos de Claude Desktop por sí sola. Mantén max_iterations en 2 o 3 en Claude Desktop; en un IDE o un marco de agentes, de 5 a 7 produce una síntesis notablemente mejor. focus_areas acepta un array si quieres dirigir cada pasada.

Generación de imágenes con grounding de búsqueda

Use gemini:generate_image with:
  prompt="Stock price chart showing Apple (AAPL) closing prices for the last 5 trading days"
  use_search=true
  aspectRatio="16:9"

El modelo predeterminado es gemini-3-pro-image, que es Nano Banana Pro ahora que salió de la vista previa. Renderiza texto legible, hace 4K y es el único que admite edición conversacional. gemini-3.1-flash-image (Nano Banana 2) es la opción rápida: no muy lejos en calidad, una fracción del tiempo y el costo. También hay una variante Lite si estás haciendo cientos.

Con use_search=true, Gemini busca cosas antes de dibujar. Clima, precios, resultados deportivos, ese tipo de imágenes basadas en datos funciona de manera confiable. El archivo de resolución completa siempre va al disco; la vista previa en línea se redimensiona para ajustarse al límite del transporte MCP, pero el original no se toca.

Generación de video con Veo 3.1

Use gemini:generate_video with:
  prompt="A close-up shot of a futuristic coffee machine brewing a glowing blue espresso, steam rising dramatically. Cinematic lighting."
  resolution="1080p"
  durationSeconds=8

Veo 3.1 de Google. Clips de cuatro a ocho segundos hasta 4K con audio nativo y sincronizado. Es asíncrono en el lado de Google y tarda de dos a cinco minutos; la herramienta consulta hasta que esté listo para que no tengas que hacerlo tú.

Opciones que vale la pena conocer:

aspectRatio - 16:9 horizontal o 9:16 para vertical
generateAudio - activado por defecto; diálogo y efectos que coinciden con el prompt
firstFrameImage - animar desde una imagen fija (así se hizo el clip de la cabina de arriba)
referenceImages - hasta tres, para consistencia de personaje o estilo
sampleCount - hasta cuatro variaciones en una sola llamada
seed - salida determinista entre ejecuciones
generateThumbnail - extrae un fotograma con ffmpeg, si lo tienes en PATH
model - veo-3.1-lite-generate-preview si quieres más barato y rápido

Generación de SVG

Esta es la que la gente subestima. La salida no es una imagen de un diagrama, es el marcado SVG en sí: colócalo en un código base, una diapositiva, una página web, y escala sin un solo artefacto de mapa de bits.

Use gemini:generate_svg with:
  prompt="Architecture diagram showing a microservices system with API gateway, three services, and a shared database"
  style="technical"
  width=1000
  height=600

Cuatro estilos:

Estilo	Mejor para
`technical`	Diagramas de arquitectura, diagramas de flujo, mapas de sistemas
`artistic`	Ilustraciones, gráficos decorativos, iconos
`minimal`	Visualizaciones de datos limpias, gráficos simples
`data-viz`	Gráficos, paneles, infografías

Obtienes código SVG real. Edítalo, anímalo, incrústalo, súbelo. Sin paso de exportación, sin Figma.

Se ejecuta en gemini-3-flash-preview a menos que pases model: es rápido, maneja el marcado SVG cómodamente y tiene un nivel gratuito. Pasa model: "gemini-3.1-pro-preview" para diagramas más densos si tienes una clave de pago.

Edición y análisis de imágenes

Edición conversacional. Nano Banana Pro mantiene el contexto entre turnos. Pasa la firma de pensamiento de la llamada anterior y recuerda en qué estaba trabajando:

Use gemini:edit_image with:
  prompt="Change the colour scheme to blue and green"
  images=[{filePath: "C:/output/gemini-123.png", thoughtSignature: "fromPreviousCall"}]

Análisis, dos herramientas para dos trabajos:

describe_image - descripciones generales rápidas en gemini-3.8-flash
analyze_image - extracción estructurada y razonamiento adecuado en gemini-3.1-pro-preview

Archivos locales:

Use gemini:load_image_from_path with filePath="C:/screenshots/error.png"

O simplemente pasa filePath directamente al array images de cualquier herramienta de imagen y el servidor lo lee por sí mismo: eso omite por completo el límite de transporte MCP.

Control de resolución de medios

Reduce el uso de tokens hasta en un 75% donde la tarea no necesita el detalle:

Nivel	Tokens	Ahorro	Mejor para
`MEDIA_RESOLUTION_LOW`	280	75%	Tareas simples, operaciones masivas
`MEDIA_RESOLUTION_MEDIUM`	560	50%	PDFs y documentos (el OCR se satura aquí)
`MEDIA_RESOLUTION_HIGH`	1120	predeterminado	Análisis detallado
`MEDIA_RESOLUTION_ULTRA_HIGH`	2000+	solo por imagen	Detalle máximo

Para OCR de PDF, MEDIUM me da extracción de texto idéntica a HIGH con la mitad de tokens. No he encontrado un caso donde no fuera así.

Generación de páginas de aterrizaje

Use gemini:generate_landing_page with:
  brief="A SaaS tool that helps developers monitor API latency"
  companyName="PingWatch"
  primaryColour="#6366F1"
  style="startup"
  sections=["hero", "features", "pricing", "cta"]

Un archivo HTML autocontenido: CSS en línea, JS vanilla, sin dependencias externas. Los estilos son minimal, bold, corporate y startup. La página de PingWatch en la galería de arriba es exactamente esta llamada.

Sistemas de diseño de gráficos profesionales

gemini_prompt_assistant lleva nueve sistemas de diseño de gráficos que puedes solicitar por nombre:

Sistema	Inspiración	Mejor para
storytelling	Cole Nussbaumer Knaflic	Presentaciones ejecutivas
financial	Financial Times	Periodismo editorial: rosa FT, títulos serif
terminal	Bloomberg / fintech	Modo oscuro de alta densidad con neón
modernist	W.E.B. Du Bois	Bloques geométricos audaces, contrastes marcados
professional	IBM Carbon / Tailwind	Paneles empresariales
editorial	FiveThirtyEight / Economist	Periodismo de datos
scientific	Nature / Science	Rigor académico
minimal	Edward Tufte	Máxima relación datos-tinta
dark	Observable	Modo oscuro moderno

Sistema de ayuda

Use gemini:gemini_help with topic="overview"

La documentación completa sin salir de Claude. Temas: overview, image_generation, image_editing, image_analysis, chat, deep_research, grounding, media_resolution, models, all.

Salida y almacenamiento de imágenes

Por defecto, las imágenes vuelven como vistas previas en línea renderizadas directamente en Claude, y el archivo de tamaño completo se escribe junto al paquete. Establece GEMINI_IMAGE_OUTPUT_DIR si prefieres que todas terminen en un lugar sensato:

"env": {
  "GEMINI_API_KEY": "your-api-key-here",
  "GEMINI_IMAGE_OUTPUT_DIR": "C:/Users/username/Pictures/gemini-output"
}

Dos archivos por imagen:

Archivo	Qué es
Resolución completa	Se guarda en disco inmediatamente, sin modificar
Vista previa	JPEG redimensionado para transporte en línea, ajustado para caber bajo el límite

Gemini devuelve imágenes de 2 a 5 MB. El redimensionado mide la sobrecarga que no es imagen en cada respuesta, calcula el presupuesto binario restante y reduce la vista previa (800, 600, 400, 300, 200 px) hasta que quepa bajo el límite de transporte MCP de 1 MB. La imagen completa siempre está en disco.

Visores integrados en Claude Desktop

Los resultados de imagen, SVG, video y página de destino se abren en un visor de la aplicación MCP con zoom, la ruta guardada y un botón de copiar. Si estás en Claude Desktop y el visor se quedaba en "Esperando imagen..." para siempre en una versión anterior, eso era Claude Desktop eliminando los datos estructurados que el visor lee (ext-apps#696). Desde la versión 2.7.0, el visor los recupera del propio servidor, por lo que se renderiza de cualquier manera.

Referencia de configuración

Variable	Obligatoria	Predeterminado	Descripción
`GEMINI_API_KEY`	Sí	-	Clave de API de Google AI de AI Studio
`GEMINI_DEFAULT_MODEL`	No	`gemini-3.1-pro-preview`	Modelo para `gemini_chat`
`GEMINI_DEEP_RESEARCH_MODEL`	No	`gemini-3.1-pro-preview`	Modelo de síntesis para `gemini_deep_research`
`GEMINI_DEEP_RESEARCH_SEARCH_MODEL`	No	`gemini-3.8-flash`	Modelo para las pasadas de búsqueda fundamentadas en `gemini_deep_research`
`GEMINI_IMAGE_ANALYSIS_MODEL`	No	`gemini-3.1-pro-preview`	Modelo para `analyze_image`
`GEMINI_IMAGE_DESCRIBE_MODEL`	No	`gemini-3.8-flash`	Modelo para `describe_image`
`GEMINI_IMAGE_GENERATION_MODEL`	No	`gemini-3-pro-image`	Modelo para `generate_image` y `edit_image`
`GEMINI_DEFAULT_GROUNDING`	No	`true`	Establécelo en `false` para desactivar la fundamentación de Búsqueda de Google de forma predeterminada
`GEMINI_IMAGE_OUTPUT_DIR`	No	-	Dónde se guardan las imágenes y videos generados
`GEMINI_ALLOW_EXPERIMENTAL`	No	`false`	Incluir modelos experimentales y de vista previa en el descubrimiento automático
`GEMINI_REQUEST_TIMEOUT_MS`	No	`240000`	Tiempo de espera por solicitud para llamadas de chat y análisis, en milisegundos
`GEMINI_MCP_RETRY_ATTEMPTS`	No	`3`	Intentos totales por solicitud a la API de Gemini. Los fallos de red transitorios (`fetch failed`, `ECONNRESET`, caídas de proxy o VPN) se reintentan con retroceso. `1` lo desactiva
`GEMINI_MCP_LOG_FILE`	No	`false`	Escribir registros en `~/.gemini-mcp/logs/`
`DEBUG_MCP`	No	`false`	Registrar en stderr para depurar llamadas de herramientas

Referencia de herramientas

Herramienta	Descripción
`gemini_chat`	Chatea con Gemini 3.1 Pro. Fundamentación de Búsqueda de Google activada de forma predeterminada. Admite `thinking_level`
`gemini_deep_research`	Pasadas de búsqueda fundamentadas en Flash, sintetizadas en un informe por 3.1 Pro. 2 pasadas predeterminadas
`gemini_list_models`	Enumera los modelos que tu clave de API puede ver, en vivo
`gemini_help`	Documentación para cada herramienta sin salir de Claude
`gemini_prompt_assistant`	Orientación experta para generación de imágenes con nueve sistemas de diseño de gráficos
`generate_image`	Generación de imágenes con fundamentación de búsqueda opcional. Resolución completa guardada en disco
`edit_image`	Edita imágenes con instrucciones en lenguaje natural. Continuidad multiturno mediante firmas de pensamiento
`describe_image`	Descripciones rápidas de imágenes en Gemini 3.8 Flash
`analyze_image`	Extracción y análisis estructurados en Gemini 3.1 Pro
`load_image_from_path`	Lee un archivo de imagen local y devuelve base64 para cualquier herramienta de imágenes
`generate_video`	Generación de video con Veo 3.1: de 4 a 8 segundos hasta 4K con audio nativo
`generate_svg`	SVG listo para producción: diagramas, ilustraciones, iconos, visualizaciones de datos
`generate_landing_page`	Páginas de destino HTML autocontenidas con CSS y JS en línea
`gemini_viewer_payload`	Interna. Los visores integrados la usan para obtener sus datos de visualización; nunca la llamarás

Referencia de modelos

Verificado contra la API de modelos en vivo el 22 de septiembre de 2026. gemini_list_models te dirá qué puede ver tu clave hoy.

Modelo	Usado por	Notas
`gemini-3.1-pro-preview`	`gemini_chat`, `gemini_deep_research` (síntesis), `analyze_image`, `generate_landing_page`	Predeterminado. Sigue siendo el modelo de razonamiento más potente que Google ofrece, con etiqueta de vista previa o no. Solo de pago: sin nivel gratuito
`gemini-3.8-flash`	`describe_image`, `gemini_deep_research` (pasadas de búsqueda)	Predeterminado. El caballo de batalla GA de Google desde septiembre de 2026; una buena opción de `gemini_chat` cuando quieres velocidad
`gemini-3-flash-preview`	`generate_svg`	Predeterminado. Tiene nivel gratuito (página de precios de Google, 24 de septiembre de 2026)
`gemini-3.7-flash`, `3.6`, `3.5`, `3.5-flash-lite`, `3.1-flash-lite`	cualquier herramienta de texto	Lanzamientos GA Flash anteriores, todos aceptados
`gemini-3-pro-image`	`generate_image`, `edit_image`	Predeterminado. Nano Banana Pro, GA. 4K, texto real, edición conversacional
`gemini-3.1-flash-image`	`generate_image`, `edit_image`	Nano Banana 2, GA. Calidad casi Pro, velocidad y precio Flash
`gemini-3.1-flash-lite-image`	`generate_image`	Nano Banana 2 Lite. El más rápido y barato
`gemini-3-pro-image-preview`, `nano-banana-pro-preview`, `gemini-2.5-flash-image`	herramientas de imagen	IDs antiguos, aún aceptados para que las configuraciones existentes sigan funcionando
`veo-3.1-generate-preview`	`generate_video`	Predeterminado. Cinematográfico, audio nativo, hasta 4K
`veo-3.1-lite-generate-preview`	`generate_video`	Más barato y rápido en la misma API

Por qué los predeterminados son lo que son. Dudé mucho sobre esto. Gemini 3.8 Flash es GA y más nuevo, pero 3.1 Pro sigue siendo lo que Google llama su modelo de razonamiento más potente, y el razonamiento es el punto de gemini_chat y la investigación profunda, así que Pro sigue siendo el predeterminado allí, y Flash asume el trabajo más ligero de describe_image. Para imágenes, Nano Banana Pro salió de vista previa y mantuvo su ventaja de calidad, así que es el predeterminado; Nano Banana 2 está ahí cuando prefieres intercambiar un poco de calidad por mucha velocidad. El modelo de video Omni más nuevo de Gemini usa una API diferente, así que aún no está conectado.

Notas de Gemini 3: la temperatura se fuerza a 1.0 en cada modelo 3.x (requisito de Google; valores más bajos causan bucles). thinking_level se aplica a gemini_chat.

Presupuestos de tokens: max_tokens predetermina al límite máximo de salida de cada modelo según lo informa en vivo la API de modelos (65,536 en los modelos de texto Gemini 3 actuales; la cifra de 1M es contexto de entrada). Es un límite, no un consumo, así que el espacio no utilizado no cuesta nada. Los valores por debajo de 4,096 se ignoran porque el pensamiento de Gemini 3 consume presupuestos pequeños antes de que veas cualquier salida, lo que parece exactamente un tiempo de espera, y los valores por encima del límite real del modelo se recortan.

Requisitos

Node.js 20.19+
Una clave de API de Gemini de Google AI Studio
ffmpeg (opcional, para miniaturas de video)

Licencia

Apache-2.0