Gemini MCP

Integra todo el poder de Gemini Pro 3 en Claude Code

Documentación

MCP Server Gemini

Un servidor de Model Context Protocol (MCP) para integrar los modelos Gemini 3 de Google con Claude Code, permitiendo una poderosa colaboración entre ambos sistemas de IA. ¡Ahora con una hermosa CLI!

Soporte de Registro MCP: ¡Ahora descubrible en el ecosistema oficial de MCP!

Características

Característica	Descripción
Deep Research Agent	Investigación autónoma en múltiples pasos con búsqueda web y citas
Token Counting	Cuenta tokens y estima costos antes de llamadas a la API
Text-to-Speech	30 voces únicas, diálogos de un solo hablante o de dos hablantes
URL Analysis	Analiza, compara y extrae datos de páginas web
Context Caching	Almacena en caché documentos grandes para consultas repetidas eficientes
YouTube Analysis	Analiza videos por URL con recorte de marcas de tiempo
Document Analysis	PDFs, DOCX, hojas de cálculo con extracción de tablas
4K Image Generation	Genera imágenes hasta 4K con 10 relaciones de aspecto
Multi-Turn Image Editing	Refina imágenes iterativamente mediante conversación
Video Generation	Crea videos con Veo 2.0 (asíncrono con sondeo)
Code Execution	Gemini escribe y ejecuta código Python (pandas, numpy, matplotlib)
Google Search	Información web en tiempo real con citas en línea
Structured Output	Respuestas JSON con validación de esquema
Data Extraction	Extrae entidades, hechos y sentimiento del texto
Thinking Levels	Controla la profundidad del razonamiento (mínimo/bajo/medio/alto)
Direct Query	Envía indicaciones a los modelos Gemini 3 Pro/Flash
Brainstorming	Resolución de problemas colaborativa entre Claude y Gemini
Code Analysis	Analiza código en busca de calidad, seguridad y rendimiento
Summarization	Resume contenido en diferentes niveles de detalle

Instalación Rápida

Servidor MCP para Claude Code

# Using npm (Recommended)
claude mcp add gemini -s user -- env GEMINI_API_KEY=YOUR_KEY npx -y @rlabs-inc/gemini-mcp

# Using bun
claude mcp add gemini -s user -- env GEMINI_API_KEY=YOUR_KEY bunx @rlabs-inc/gemini-mcp

CLI (Instalación Global)

# Install globally
npm install -g @rlabs-inc/gemini-mcp

# Set your API key once (stored securely)
gcli config set api-key YOUR_KEY

# Now use any command!
gcli search "latest news"
glci image "sunset over mountains" --ratio 16:9

Obtén tu clave de API: Visita Google AI Studio - ¡es gratis y toma segundos!

Opciones de Instalación

# With verbose logging
claude mcp add gemini -s user -- env GEMINI_API_KEY=YOUR_KEY VERBOSE=true bunx -y @rlabs-inc/gemini-mcp

# With custom output directory for generated images/videos
claude mcp add gemini -s user -- env GEMINI_API_KEY=YOUR_KEY GEMINI_OUTPUT_DIR=/path/to/output bunx -y @rlabs-inc/gemini-mcp

Herramientas Disponibles

gemini-query

Consultas directas a Gemini con control del nivel de pensamiento:

prompt: "Explain quantum entanglement"
model: "pro" or "flash"
thinkingLevel: "low" | "medium" | "high" (optional)

low: Respuestas rápidas, razonamiento mínimo
medium: Equilibrado (solo Flash)
high: Razonamiento profundo para tareas complejas (predeterminado)

gemini-generate-image

Genera imágenes con Nano Banana Pro (¡Claude puede VERLAS!):

prompt: "a futuristic city at sunset"
style: "cyberpunk" (optional)
aspectRatio: "16:9" (1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9)
imageSize: "2K" (1K, 2K, 4K)
useGoogleSearch: false (ground in real-world info)
thinkingLevel: "high" (optional - minimal, low, medium, high)
personGeneration: "ALLOW_ALL" (optional - ALLOW_ALL, ALLOW_ADULT, ALLOW_NONE)
seed: 42 (optional - for reproducible results)

gemini-start-image-edit

Inicia una sesión de edición de imágenes de múltiples turnos:

prompt: "a cozy cabin in the mountains"
aspectRatio: "16:9"
imageSize: "2K"
useGoogleSearch: false
thinkingLevel: "high" (optional - minimal, low, medium, high)
personGeneration: "ALLOW_ALL" (optional - ALLOW_ALL, ALLOW_ADULT, ALLOW_NONE)
seed: 42 (optional - for reproducible results)

Devuelve un ID de sesión para edición iterativa.

gemini-continue-image-edit

Continúa refinando una imagen:

sessionId: "edit-123456789"
prompt: "add snow on the roof and make it nighttime"

gemini-end-image-edit

Cierra una sesión de edición:

sessionId: "edit-123456789"

gemini-list-image-sessions

Lista todas las sesiones de edición activas.

gemini-generate-video

Genera videos usando Veo:

prompt: "a cat playing piano"
aspectRatio: "16:9" (optional)
negativePrompt: "blurry, text" (optional)

La generación de videos es asíncrona (toma 1-5 minutos). Usa gemini-check-video para sondear.

gemini-check-video

Comprueba el estado de generación del video y descárgalo cuando esté completo:

operationId: "operations/xxx-xxx-xxx"

gemini-analyze-code

Analiza código en busca de problemas:

code: "function foo() { ... }"
language: "typescript" (optional)
focus: "quality" | "security" | "performance" | "bugs" | "general"

gemini-analyze-text

Analiza contenido de texto:

text: "Your text here..."
type: "sentiment" | "summary" | "entities" | "key-points" | "general"

gemini-brainstorm

Lluvia de ideas colaborativa:

prompt: "How could we implement real-time collaboration?"
claudeThoughts: "I think we should use WebSockets..."
maxRounds: 3 (optional)

gemini-summarize

Resume contenido:

content: "Long text to summarize..."
length: "brief" | "moderate" | "detailed"
format: "paragraph" | "bullet-points" | "outline"

gemini-run-code

Deja que Gemini escriba y ejecute código Python:

prompt: "Calculate the first 50 prime numbers and plot them"
data: "optional CSV data to analyze" (optional)

Soporta bibliotecas: numpy, pandas, matplotlib, scipy, scikit-learn, tensorflow y más. Los gráficos generados se guardan en el directorio de salida y se devuelven como imágenes.

gemini-search

Búsqueda web en tiempo real con citas:

query: "What happened in tech news this week?"
returnCitations: true (default)

Devuelve respuestas fundamentadas con citas en línea y URL de fuentes.

gemini-structured

Obtén respuestas JSON que coincidan con un esquema:

prompt: "Extract the meeting details from this email..."
schema: '{"type":"object","properties":{"date":{"type":"string"},"attendees":{"type":"array"}}}'
useGoogleSearch: false (optional)

gemini-extract

Herramienta conveniente para patrones de extracción comunes:

text: "Your text to analyze..."
extractType: "entities" | "facts" | "summary" | "keywords" | "sentiment" | "custom"
customFields: "name, date, amount" (for custom extraction)

gemini-youtube

Analiza videos de YouTube directamente:

url: "https://www.youtube.com/watch?v=..."
question: "What happens at 2:30?"
startTime: "1m30s" (optional, for clipping)
endTime: "5m00s" (optional, for clipping)

gemini-youtube-summary

Resumen rápido de videos:

url: "https://www.youtube.com/watch?v=..."
style: "brief" | "detailed" | "bullet-points" | "chapters"

gemini-analyze-document

Analiza PDFs y documentos:

filePath: "/path/to/document.pdf"
question: "Summarize the key findings"
mediaResolution: "low" | "medium" | "high"

gemini-summarize-pdf

Resumen rápido de PDFs:

filePath: "/path/to/document.pdf"
style: "brief" | "detailed" | "outline" | "key-points"

gemini-extract-tables

Extrae tablas de documentos:

filePath: "/path/to/document.pdf"
outputFormat: "markdown" | "csv" | "json"

Flujo de Trabajo: Claude + Gemini

La combinación asesina para el desarrollo:

Claude	Gemini
Lógica compleja	Frontend/UI
Arquitectura	Componentes visuales
Código backend	Generación de imágenes
Integración	Estilos React/CSS
Razonamiento	Generación creativa

Ejemplo de flujo de trabajo:

Pídele a Claude que diseñe la API del backend
Usa gemini-generate-image para maquetas de UI
Pídele a Gemini que genere componentes React mediante gemini-query
Usa la edición de múltiples turnos para refinar los visuales
Deja que Claude conecte todo

Variables de Entorno

Variable	Requerida	Predeterminado	Descripción
`GEMINI_API_KEY`	Sí	-	Tu clave de API de Google Gemini
`GEMINI_OUTPUT_DIR`	No	`./gemini-output`	Dónde guardar los archivos generados
`GEMINI_MODEL`	No	-	Modelo de anulación para la prueba de inicio
`GEMINI_PRO_MODEL`	No	`gemini-3-pro-preview`	Modelo Pro (Gemini 3)
`GEMINI_FLASH_MODEL`	No	`gemini-3-flash-preview`	Modelo Flash (Gemini 3)
`GEMINI_IMAGE_MODEL`	No	`gemini-3-pro-image-preview`	Modelo de imagen (Nano Banana Pro)
`GEMINI_IMAGE_THINKING_LEVEL`	No	`high`	Nivel de pensamiento predeterminado para la generación de imágenes (mínimo, bajo, medio, alto)
`GEMINI_VIDEO_MODEL`	No	`veo-2.0-generate-001`	Modelo de video
`VERBOSE`	No	`false`	Habilitar registro detallado
`QUIET`	No	`false`	Minimizar registro
`GEMINI_ENABLED_TOOLS`	No	-	Lista separada por comas de grupos de herramientas a cargar (p. ej., `query,search,image-gen`)
`GEMINI_TOOL_PRESET`	No	-	Perfil preestablecido: `minimal`, `text`, `image`, `research`, `media`, `full`

Configuración de Herramientas

Por defecto, se cargan las 37 herramientas. Para reducir el uso de contexto, configura qué herramientas cargar:

Preestablecidos Disponibles

Preestablecido	Grupos de Herramientas
`minimal`	query, brainstorm
`text`	query, brainstorm, analyze, summarize, structured
`image`	query, image-gen, image-edit, image-analyze
`research`	query, search, deep-research, url-context, document
`media`	query, image-gen, image-edit, image-analyze, video-gen, youtube, speech
`full`	Todos los 18 grupos de herramientas (predeterminado)

Usando Preestablecidos

# Minimal - query and brainstorm
GEMINI_TOOL_PRESET=minimal

# Text processing
GEMINI_TOOL_PRESET=text  # query, brainstorm, analyze, summarize, structured

# Image workflows
GEMINI_TOOL_PRESET=image  # query, image-gen, image-edit, image-analyze

# Research workflows
GEMINI_TOOL_PRESET=research  # query, search, deep-research, url-context, document

Usando Listas de Herramientas Explícitas

# Only specific tools
GEMINI_ENABLED_TOOLS=query,search,image-gen

Combinando Preestablecido + Explícito

# Start with preset, add extras
GEMINI_TOOL_PRESET=minimal
GEMINI_ENABLED_TOOLS=search,image-gen  # Adds to minimal preset

Grupos de Herramientas Disponibles

Grupo	Herramientas
`query`	gemini-query
`brainstorm`	gemini-brainstorm
`analyze`	gemini-analyze-code, gemini-analyze-text
`summarize`	gemini-summarize
`image-gen`	gemini-generate-image, gemini-image-prompt
`image-edit`	gemini-start-image-edit, gemini-continue-image-edit, gemini-end-image-edit, gemini-list-image-sessions
`video-gen`	gemini-generate-video, gemini-check-video
`code-exec`	gemini-run-code
`search`	gemini-search
`structured`	gemini-structured, gemini-extract
`youtube`	gemini-youtube, gemini-youtube-summary
`document`	gemini-analyze-document, gemini-summarize-pdf, gemini-extract-tables
`url-context`	gemini-analyze-url, gemini-compare-urls, gemini-extract-from-url
`cache`	gemini-create-cache, gemini-query-cache, gemini-list-caches, gemini-delete-cache
`speech`	gemini-speak, gemini-dialogue, gemini-list-voices
`token-count`	gemini-count-tokens
`deep-research`	gemini-deep-research, gemini-check-research, gemini-research-followup
`image-analyze`	gemini-analyze-image

Instalación Manual

Instalación Global

# Using npm
npm install -g @rlabs-inc/gemini-mcp

# Using bun
bun install -g @rlabs-inc/gemini-mcp

Configuración de Claude Code

{
  "gemini": {
    "command": "npx",
    "args": ["-y", "@rlabs-inc/gemini-mcp"],
    "env": {
      "GEMINI_API_KEY": "your-api-key",
      "GEMINI_OUTPUT_DIR": "/path/to/save/files"
    }
  }
}

Si debes usar un proxy para establecer una conexión con gemini, reemplaza xxxx con tu puerto de proxy real:

{
  "gemini": {
    "command": "npx",
    "args": ["-y", "@rlabs-inc/gemini-mcp"],
    "env": {
      "GEMINI_API_KEY": "your-api-key",
      "GEMINI_OUTPUT_DIR": "/path/to/save/files",
      "HTTP_PROXY": "http://127.0.0.1:xxxx",
      "HTTPS_PROXY": "http://127.0.0.1:xxxx"
    }
  }
}

Solución de Problemas

Límites de Tasa (Errores 429)

Si estás alcanzando los límites de tasa en el nivel gratuito:

Establece GEMINI_MODEL=gemini-3-flash-preview para usar Flash en la inicialización (límites más altos)
O actualiza a un plan de pago

Problemas de Conexión

Verifica tu clave de API en Google AI Studio
Comprueba el estado del servidor: claude mcp list
Prueba con registro detallado: VERBOSE=true

Problemas de Imagen/Video

Asegúrate de que tu clave de API tenga acceso a la generación de imágenes/videos
Comprueba los permisos del directorio de salida
Los archivos se guardan en GEMINI_OUTPUT_DIR (predeterminado: ./gemini-output)
Para imágenes 4K, la generación tarda más

Versiones Anteriores

0.7.2

¡Hermosa CLI con Temas! Usa Gemini directamente desde tu terminal:

# Install globally
npm install -g @rlabs-inc/gemini-mcp

# Set your API key once
gcli config set api-key YOUR_KEY

# Generate images, videos, search, research, and more!
gcli image "a cat astronaut" --size 4K
gcli search "latest AI news"
gcli research "quantum computing applications" --wait
gcli speak "Hello world" --voice Puck

5 Temas Hermosos: terminal, neon, ocean, forest, minimal

Comandos CLI:

gcli query - Consultas directas a Gemini con niveles de pensamiento
gcli search - Búsqueda web en tiempo real con citas
gcli research - Agente de investigación profunda
gcli image - Genera imágenes (hasta 4K)
gcli video - Genera videos con Veo
gcli speak - Texto a voz con 30 voces
gcli tokens - Cuenta tokens y estima costos
gcli config - Administra la configuración

v0.6.x: Deep Research, Token Counting, TTS, URL analysis, Context Caching v0.5.x: 30+ tools, YouTube analysis, Document analysis v0.4.x: Code execution, Google Search v0.3.x: Thinking levels, Structured output, 4K images v0.2.x: Image/Video generation with Veo

Desarrollo

git clone https://github.com/rlabs-inc/gemini-mcp.git
cd gemini-mcp
bun install
bun run build
bun run dev -- --verbose

Scripts

Comando	Descripción
`bun run build`	Compilar para producción
`bun run dev`	Modo de desarrollo con observación
`bun run typecheck`	Verificación de tipos sin emitir
`bun run format`	Formatear con Prettier
`bun run lint`	Lint con ESLint

Licencia

Licencia MIT

Hecho con Claude + Gemini trabajando juntos