Gemini MCP

Integre todo o poder do Gemini Pro 3 ao Claude Code

Documentação

MCP Server Gemini

Um servidor Model Context Protocol (MCP) para integrar os modelos Gemini 3 do Google com o Claude Code, permitindo uma colaboração poderosa entre ambos os sistemas de IA. Agora com uma linda CLI!

Suporte ao Registro MCP: Agora localizável no ecossistema MCP oficial!

Recursos

Recurso	Descrição
Agente de Pesquisa Aprofundada	Pesquisa autônoma em múltiplas etapas com busca na web e citações
Contagem de Tokens	Conte tokens e estime custos antes das chamadas de API
Texto para Fala	30 vozes únicas, um único locutor ou diálogos de dois locutores
Análise de URL	Analise, compare e extraia dados de páginas da web
Cache de Contexto	Armazene documentos grandes em cache para consultas repetidas eficientes
Análise do YouTube	Analise vídeos por URL com recorte de timestamps
Análise de Documentos	PDFs, DOCX, planilhas com extração de tabelas
Geração de Imagens 4K	Gere imagens de até 4K com 10 proporções de aspecto
Edição de Imagens Multi-Turn	Refine imagens iterativamente através de conversa
Geração de Vídeos	Crie vídeos com Veo 2.0 (assíncrono com polling)
Execução de Código	Gemini escreve e executa código Python (pandas, numpy, matplotlib)
Pesquisa Google	Informações da web em tempo real com citações inline
Saída Estruturada	Respostas JSON com validação de schema
Extração de Dados	Extraia entidades, fatos, sentimentos de texto
Níveis de Raciocínio	Controle a profundidade do raciocínio (mínimo/baixo/médio/alto)
Consulta Direta	Envie prompts para os modelos Gemini 3 Pro/Flash
Brainstorming	Resolução colaborativa de problemas Claude + Gemini
Análise de Código	Analise código para qualidade, segurança, desempenho
Resumo	Resuma conteúdo em diferentes níveis de detalhe

Instalação 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 (Instalação 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

Obtenha sua chave de API: Visite Google AI Studio - é gratuito e leva segundos!

Opções de Instalação

# 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

Ferramentas Disponíveis

gemini-query

Consultas diretas ao Gemini com controle de nível de raciocínio:

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

baixo: Respostas rápidas, raciocínio mínimo
médio: Equilibrado (somente Flash)
alto: Raciocínio profundo para tarefas complexas (padrão)

gemini-generate-image

Gere imagens com Nano Banana Pro (Claude pode VÊ-LAS!):

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

Inicie uma sessão de edição de imagens multi-turn:

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)

Retorna um ID de sessão para edição iterativa.

gemini-continue-image-edit

Continue refinando uma imagem:

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

gemini-end-image-edit

Encerre uma sessão de edição:

sessionId: "edit-123456789"

gemini-list-image-sessions

Liste todas as sessões de edição ativas.

gemini-generate-video

Gere vídeos usando Veo:

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

A geração de vídeos é assíncrona (leva 1-5 minutos). Use gemini-check-video para fazer polling.

gemini-check-video

Verifique o status da geração de vídeos e baixe quando concluída:

operationId: "operations/xxx-xxx-xxx"

gemini-analyze-code

Analise código em busca de problemas:

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

gemini-analyze-text

Analise conteúdo de texto:

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

gemini-brainstorm

Brainstorming colaborativo:

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

gemini-summarize

Resuma conteúdo:

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

gemini-run-code

Deixe Gemini escrever e executar código Python:

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

Suporta bibliotecas: numpy, pandas, matplotlib, scipy, scikit-learn, tensorflow e outras. Os gráficos gerados são salvos no diretório de saída e retornados como imagens.

gemini-search

Pesquisa web em tempo real com citações:

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

Retorna respostas fundamentadas com citações inline e URLs de origem.

gemini-structured

Obtenha respostas JSON que correspondem a um schema:

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

gemini-extract

Ferramenta conveniente para padrões comuns de extração:

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

gemini-youtube

Analise vídeos do YouTube diretamente:

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

Resumo rápido de vídeos:

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

gemini-analyze-document

Analise PDFs e documentos:

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

gemini-summarize-pdf

Resumo rápido de PDFs:

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

gemini-extract-tables

Extraia tabelas de documentos:

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

Fluxo de Trabalho: Claude + Gemini

A combinação matadora para desenvolvimento:

Claude	Gemini
Lógica complexa	Frontend/UI
Arquitetura	Componentes visuais
Código backend	Geração de imagens
Integração	Estilização React/CSS
Raciocínio	Geração criativa

Exemplo de fluxo de trabalho:

Peça ao Claude para projetar a API backend
Use gemini-generate-image para mockups de UI
Peça ao Gemini para gerar componentes React via gemini-query
Use edição multi-turn para refinar os visuais
Deixe o Claude conectar tudo

Variáveis de Ambiente

Variável	Obrigatória	Padrão	Descrição
`GEMINI_API_KEY`	Sim	-	Sua chave de API do Google Gemini
`GEMINI_OUTPUT_DIR`	Não	`./gemini-output`	Onde salvar arquivos gerados
`GEMINI_MODEL`	Não	-	Sobrescrever modelo para teste de inicialização
`GEMINI_PRO_MODEL`	Não	`gemini-3-pro-preview`	Modelo Pro (Gemini 3)
`GEMINI_FLASH_MODEL`	Não	`gemini-3-flash-preview`	Modelo Flash (Gemini 3)
`GEMINI_IMAGE_MODEL`	Não	`gemini-3-pro-image-preview`	Modelo de imagem (Nano Banana Pro)
`GEMINI_IMAGE_THINKING_LEVEL`	Não	`high`	Nível de raciocínio padrão para geração de imagens (mínimo, baixo, médio, alto)
`GEMINI_VIDEO_MODEL`	Não	`veo-2.0-generate-001`	Modelo de vídeo
`VERBOSE`	Não	`false`	Ativar logging detalhado
`QUIET`	Não	`false`	Minimizar logging
`GEMINI_ENABLED_TOOLS`	Não	-	Lista separada por vírgulas de grupos de ferramentas para carregar (ex.: `query,search,image-gen`)
`GEMINI_TOOL_PRESET`	Não	-	Perfil predefinido: `minimal`, `text`, `image`, `research`, `media`, `full`

Configuração de Ferramentas

Por padrão, todas as 37 ferramentas são carregadas. Para reduzir o uso de contexto, configure quais ferramentas carregar:

Perfis Disponíveis

Perfil	Grupos de Ferramentas
`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 os 18 grupos de ferramentas (padrão)

Usando Perfis

# 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 Explícitas de Ferramentas

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

Combinando Perfil + Explícito

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

Grupos de Ferramentas Disponíveis

Grupo	Ferramentas
`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

Instalação Manual

Instalação Global

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

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

Configuração do 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"
    }
  }
}

Se você precisar usar um proxy para estabelecer uma conexão com o gemini, substitua xxxx pela sua porta 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"
    }
  }
}

Solução de Problemas

Limites de Taxa (Erros 429)

Se você está atingindo limites de taxa no nível gratuito:

Defina GEMINI_MODEL=gemini-3-flash-preview para usar Flash na inicialização (limites mais altos)
Ou faça upgrade para um plano pago

Problemas de Conexão

Verifique sua chave de API no Google AI Studio
Verifique o status do servidor: claude mcp list
Tente com logging detalhado: VERBOSE=true

Problemas com Imagens/Vídeos

Certifique-se de que sua chave de API tem acesso à geração de imagens/vídeos
Verifique as permissões do diretório de saída
Os arquivos são salvos em GEMINI_OUTPUT_DIR (padrão: ./gemini-output)
Para imagens 4K, a geração leva mais tempo

Versões Anteriores

0.7.2

Linda CLI com Temas! Use o Gemini diretamente do seu 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 Bonitos: terminal, neon, ocean, forest, minimal

Comandos CLI:

gcli query - Consultas diretas ao Gemini com níveis de raciocínio
gcli search - Pesquisa web em tempo real com citações
gcli research - Agente de pesquisa aprofundada
gcli image - Gere imagens (até 4K)
gcli video - Gere vídeos com Veo
gcli speak - Texto para fala com 30 vozes
gcli tokens - Conte tokens e estime custos
gcli config - Gerencie configurações

v0.6.x: Pesquisa Aprofundada, Contagem de Tokens, TTS, análise de URL, Cache de Contexto v0.5.x: 30+ ferramentas, análise do YouTube, análise de documentos v0.4.x: Execução de código, Pesquisa Google v0.3.x: Níveis de raciocínio, saída estruturada, imagens 4K v0.2.x: Geração de imagens/vídeos com Veo

Desenvolvimento

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

Scripts

Comando	Descrição
`bun run build`	Compilar para produção
`bun run dev`	Modo de desenvolvimento com watch
`bun run typecheck`	Verificação de tipos sem emitir
`bun run format`	Formatar com Prettier
`bun run lint`	Lint com ESLint

Licença

Licença MIT

Feito com Claude + Gemini trabalhando juntos