Gemini MCP

Integre a saída do Gemini fundamentada em pesquisa ao seu fluxo de trabalho.

Documentação

Gemini MCP - Geração de imagens, vídeo e busca integrada do Google Gemini dentro do Claude

Tenho este servidor MCP do Gemini rodando na minha configuração do Claude Desktop há quase um ano. É um dos poucos que deixo ligado permanentemente. Não porque o Gemini substitui o Claude (não substitui), mas porque busca integrada, geração de imagens, diagramas SVG e vídeo são coisas que o Gemini faz bem, e tê-las como ferramentas dentro do Claude é melhor do que ficar alternando entre abas do navegador.

Quatorze ferramentas, construídas em torno dos modelos que as pessoas realmente procuram: Nano Banana Pro (gemini-3-pro-image) e Nano Banana 2 para imagens, Veo 3.1 para vídeo com áudio sincronizado, e Gemini 3.1 Pro para chat e pesquisa aprofundada com integração ao Google Search. Tudo é pré-visualizado inline no Claude Desktop através de MCP Apps, em vez de virar um caminho de arquivo que você precisa abrir.

Um comando npx. Só isso.

Navegação rápida

O que ele cria | Comece agora | O que ele faz | Saída de imagens | Configuração | Ferramentas | Modelos | Requisitos

O que ele cria

Tudo abaixo saiu das ferramentas deste repositório, sem retoques, na tarde em que escrevi isto. Os prompts estão nas legendas para você julgar por conta própria.

Geração de imagens com busca integrada. Uma chamada generate_image com use_search=true. O Gemini consultou a previsão real do Met Office para a semana e depois desenhou. As datas e temperaturas são reais (bem, tão reais quanto uma previsão pode ser).

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

Prompt: "Um pôster editorial polido de infográfico: clima em Londres, esta semana. Use dados reais de previsão da busca para os próximos 5 dias..." - gemini-3-pro-image, 16:9, 2K.

Texto que é realmente escrito corretamente. Esta é a coisa que o Nano Banana Pro faz que a geração anterior de modelos de imagem não conseguia. Cada rótulo aqui saiu direto do modelo.

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

Prompt: "Um infográfico limpo, com qualidade de revista, intitulado Como funciona uma chamada de ferramenta MCP, com quatro etapas numeradas..." - gemini-3-pro-image.

Gerar e depois editar. À esquerda está generate_image. À direita está edit_image nesse arquivo com uma frase de instruções: mude a pista para Monza à luz do dia, troque a iluminação de contorno por luz de janela, deixe os pedais vermelhos. Mesma cabine, mesmo ângulo de câmera.

`generate_image`	`edit_image`

Imagem para vídeo com Veo 3.1. A cabine noturna acima, passada para generate_video como firstFrameImage. Oito segundos em 1080p com áudio gerado (som do motor, chiado dos pneus) - o GIF abaixo está silencioso e compactado para o GitHub, o arquivo real é um MP4 de verdade.

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

SVG que você pode realmente usar. Não é uma imagem de diagrama - é marcação vetorial real que você pode colocar em uma página, editar manualmente ou enviar para um repositório. Ambos são os arquivos .svg brutos que a ferramenta gravou em disco.

`generate_svg` style=technical	`generate_svg` style=data-viz

Uma página de destino a partir de um parágrafo. generate_landing_page com um briefing, um nome de empresa e uma cor de marca. HTML autocontido, CSS inline, o pequeno gráfico no herói é SVG animado. Captura de tela do arquivo aberto no Chrome, nada mais foi tocado.

Generated SaaS landing page rendered in a browser

E o rápido. Nano Banana 2 (gemini-3.1-flash-image) para quando você quer volume em vez de 4K. Isso levou cerca de dez segundos.

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

Comece em dois minutos

Passo 1: Obtenha uma chave de API do Gemini

Vá para Google AI Studio e crie uma.

Uma palavra sobre o nível gratuito, porque os padrões dependem de um modelo pago. A página de preços do Google (em 24 de setembro de 2026) dá ao Gemini 3 Flash Preview um nível gratuito, mas o Gemini 3.1 Pro Preview é apenas pago - e o 3.1 Pro é o padrão para gemini_chat, gemini_deep_research (síntese), analyze_image e generate_landing_page. Em uma chave gratuita, essas chamadas falharão a menos que você as aponte para um modelo gratuito: defina GEMINI_DEFAULT_MODEL=gemini-3-flash-preview (cobre chat e páginas de destino), GEMINI_DEEP_RESEARCH_MODEL e GEMINI_IMAGE_ANALYSIS_MODEL da mesma forma, ou passe model por chamada. generate_svg já usa como padrão gemini-3-flash-preview. Verifique a página de preços para os outros modelos antes de depender deles - o Google muda esses níveis.

Passo 2: Adicione à sua configuração do Claude Desktop

Locais dos arquivos de configuração:

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"
      }
    }
  }
}

Passo 3: Reinicie o Claude Desktop

Só isso. As ferramentas aparecem automaticamente. npx baixa o pacote na primeira execução, então não há instalação separada.

Build local em vez disso

Para desenvolvimento, ou se preferir não depender do npx:

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

Depois aponte sua configuração para o build 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)

O Claude Code não lê claude_desktop_config.json. Use claude mcp add em vez disso:

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

Com um diretório de saída para imagens e vídeo:

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

Verifique com claude mcp get gemini - você quer ver Status: Connected.

O que ele faz

Chat com integração ao Google Search

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

A integração está ativada por padrão. O Gemini pesquisa no Google antes de responder, então você obtém informações deste mês em vez de um palpite com data de corte do treinamento, e as fontes voltam como links markdown. Para perguntas onde você quer raciocínio puro ("explique este código", esse tipo de coisa), defina grounding: false.

Roda em gemini-3.1-pro-preview a menos que você diga o contrário. Passe model: "gemini-3.8-flash" se preferir velocidade em vez de profundidade. thinking_level funciona em todos os modelos Gemini 3.x: high para o trabalho difícil, low para manter a agilidade.

Pesquisa aprofundada

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

Executa passagens de busca integrada e depois as transforma em um relatório. As passagens rodam em gemini-3.8-flash com pensamento baixo (estão coletando fatos, não raciocinando sobre eles), e a síntese no final roda em gemini-3.1-pro-preview com pensamento alto. Duas passagens mais uma síntese é o padrão e leva de dois a três minutos.

Essa divisão importa mais do que parece. Versões anteriores rodavam tudo no Pro com pensamento completo, e uma única passagem em uma pergunta ampla podia estourar o timeout de quatro minutos do Claude Desktop sozinha. Mantenha max_iterations em 2 ou 3 no Claude Desktop; em um IDE ou framework de agente, 5 a 7 produz uma síntese visivelmente melhor. focus_areas aceita um array se você quiser direcionar cada passagem.

Geração de imagens com busca integrada

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"

O modelo padrão é gemini-3-pro-image, que é o Nano Banana Pro agora que saiu da pré-visualização. Ele renderiza texto legível, faz 4K, e é o único que suporta edição conversacional. gemini-3.1-flash-image (Nano Banana 2) é a opção rápida - não muito distante em qualidade, uma fração do tempo e do custo. Há também uma variante Lite se você estiver fazendo centenas.

Com use_search=true, o Gemini pesquisa antes de desenhar. Clima, preços, resultados esportivos, esse tipo de imagem orientada por dados funciona de forma confiável. O arquivo em resolução total sempre vai para o disco; a pré-visualização inline é redimensionada para caber no limite do transporte MCP, mas o original fica intacto.

Geração de vídeo com 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

O Veo 3.1 do Google. Clipes de quatro a oito segundos em até 4K com áudio nativo e sincronizado. É assíncrono no lado do Google e leva de dois a cinco minutos; a ferramenta faz polling até ficar pronta para que você não precise.

Opções que valem a pena conhecer:

aspectRatio - 16:9 paisagem ou 9:16 para vertical
generateAudio - ativado por padrão; diálogo e efeitos que combinam com o prompt
firstFrameImage - animar a partir de uma imagem estática (foi assim que o clipe da cabine acima foi feito)
referenceImages - até três, para consistência de personagem ou estilo
sampleCount - até quatro variações em uma única chamada
seed - saída determinística entre execuções
generateThumbnail - extrai um quadro com ffmpeg, se você o tiver no PATH
model - veo-3.1-lite-generate-preview se você quiser mais barato e mais rápido

Geração de SVG

Esta é a que as pessoas subestimam. A saída não é uma imagem de diagrama, é a marcação SVG em si - coloque-a em um código, um slide, uma página web, e ela escala sem um único artefato raster.

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

Quatro estilos:

Estilo	Melhor para
`technical`	Diagramas de arquitetura, fluxogramas, mapas de sistemas
`artistic`	Ilustrações, gráficos decorativos, ícones
`minimal`	Visualizações de dados limpas, gráficos simples
`data-viz`	Gráficos, dashboards, infográficos

Você recebe código SVG real de volta. Edite, anime, incorpore, envie. Sem etapa de exportação, sem Figma.

Roda em gemini-3-flash-preview a menos que você passe model - é rápido, lida confortavelmente com marcação SVG e tem nível gratuito. Passe model: "gemini-3.1-pro-preview" para diagramas mais densos se você estiver em uma chave paga.

Edição e análise de imagens

Edição conversacional. O Nano Banana Pro mantém contexto entre turnos. Passe a assinatura de pensamento da chamada anterior de volta e ele lembra no que estava trabalhando:

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

Análise, duas ferramentas para dois trabalhos:

describe_image - descrições gerais rápidas em gemini-3.8-flash
analyze_image - extração estruturada e raciocínio adequado em gemini-3.1-pro-preview

Arquivos locais:

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

Ou apenas passe filePath diretamente para o array images de qualquer ferramenta de imagem e o servidor lê por conta própria - isso ignora completamente o limite de transporte MCP.

Controle de resolução de mídia

Reduza o uso de tokens em até 75% onde a tarefa não precisa do detalhe:

Nível	Tokens	Economia	Melhor para
`MEDIA_RESOLUTION_LOW`	280	75%	Tarefas simples, operações em lote
`MEDIA_RESOLUTION_MEDIUM`	560	50%	PDFs e documentos (OCR satura aqui)
`MEDIA_RESOLUTION_HIGH`	1120	padrão	Análise detalhada
`MEDIA_RESOLUTION_ULTRA_HIGH`	2000+	apenas por imagem	Detalhe máximo

Para OCR de PDF, MEDIUM me dá extração de texto idêntica ao HIGH com metade dos tokens. Nunca encontrei um caso onde não funcionasse.

Geração de páginas de destino

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"]

Um único arquivo HTML autocontido: CSS inline, JS vanilla, sem dependências externas. Os estilos são minimal, bold, corporate e startup. A página PingWatch na galeria acima é exatamente esta chamada.

Sistemas profissionais de design de gráficos

gemini_prompt_assistant carrega nove sistemas de design de gráficos que você pode solicitar pelo nome:

Sistema	Inspiração	Melhor para
storytelling	Cole Nussbaumer Knaflic	Apresentações executivas
financial	Financial Times	Jornalismo editorial - rosa FT, títulos serifados
terminal	Bloomberg / fintech	Modo escuro de alta densidade com neon
modernist	W.E.B. Du Bois	Blocos geométricos ousados, contrastes fortes
professional	IBM Carbon / Tailwind	Dashboards empresariais
editorial	FiveThirtyEight / Economist	Jornalismo de dados
scientific	Nature / Science	Rigor acadêmico
minimal	Edward Tufte	Máxima proporção de tinta de dados
dark	Observable	Modo escuro moderno

Sistema de ajuda

Use gemini:gemini_help with topic="overview"

A documentação completa sem sair do Claude. Tópicos: overview, image_generation, image_editing, image_analysis, chat, deep_research, grounding, media_resolution, models, all.

Saída e armazenamento de imagens

Por padrão, as imagens voltam como pré-visualizações inline renderizadas diretamente no Claude, e o arquivo em tamanho total é gravado ao lado do pacote. Defina GEMINI_IMAGE_OUTPUT_DIR se preferir que todas caiam em um lugar sensato:

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

Dois arquivos por imagem:

Arquivo	O que é
Resolução total	Salvo em disco imediatamente, sem alterações
Pré-visualização	JPEG redimensionado para transporte inline, dimensionado para caber abaixo do limite

O Gemini retorna imagens de 2 a 5 MB. O redimensionamento mede a sobrecarga não relacionada a imagens em cada resposta, calcula o orçamento binário restante e reduz a pré-visualização (800, 600, 400, 300, 200px) até caber abaixo do limite de transporte MCP de 1 MB. A imagem completa está sempre disponível no disco.

Visualizadores inline no Claude Desktop

Resultados de imagem, SVG, vídeo e página de destino abrem em um visualizador de aplicativo MCP com zoom, caminho salvo e botão de copiar. Se você estiver no Claude Desktop e o visualizador ficou em "Waiting for image..." para sempre em uma versão anterior, isso era o Claude Desktop removendo os dados estruturados que o visualizador lê (ext-apps#696). Desde a versão 2.7.0, o visualizador busca esses dados de volta do próprio servidor, então ele renderiza de qualquer forma.

Referência de configuração

Variável	Obrigatória	Padrão	Descrição
`GEMINI_API_KEY`	Sim	-	Chave de API do Google AI do AI Studio
`GEMINI_DEFAULT_MODEL`	Não	`gemini-3.1-pro-preview`	Modelo para `gemini_chat`
`GEMINI_DEEP_RESEARCH_MODEL`	Não	`gemini-3.1-pro-preview`	Modelo de síntese para `gemini_deep_research`
`GEMINI_DEEP_RESEARCH_SEARCH_MODEL`	Não	`gemini-3.8-flash`	Modelo para as passagens de pesquisa fundamentada em `gemini_deep_research`
`GEMINI_IMAGE_ANALYSIS_MODEL`	Não	`gemini-3.1-pro-preview`	Modelo para `analyze_image`
`GEMINI_IMAGE_DESCRIBE_MODEL`	Não	`gemini-3.8-flash`	Modelo para `describe_image`
`GEMINI_IMAGE_GENERATION_MODEL`	Não	`gemini-3-pro-image`	Modelo para `generate_image` e `edit_image`
`GEMINI_DEFAULT_GROUNDING`	Não	`true`	Defina como `false` para desativar a fundamentação da Pesquisa Google por padrão
`GEMINI_IMAGE_OUTPUT_DIR`	Não	-	Onde imagens e vídeos gerados são salvos
`GEMINI_ALLOW_EXPERIMENTAL`	Não	`false`	Incluir modelos experimentais e de pré-visualização na descoberta automática
`GEMINI_REQUEST_TIMEOUT_MS`	Não	`240000`	Tempo limite por solicitação para chamadas de chat e análise, em milissegundos
`GEMINI_MCP_RETRY_ATTEMPTS`	Não	`3`	Total de tentativas por solicitação à API do Gemini. Falhas de rede transitórias (`fetch failed`, `ECONNRESET`, quedas de proxy ou VPN) são repetidas com backoff. `1` desativa isso
`GEMINI_MCP_LOG_FILE`	Não	`false`	Gravar logs em `~/.gemini-mcp/logs/`
`DEBUG_MCP`	Não	`false`	Registrar em stderr para depurar chamadas de ferramentas

Referência de ferramentas

Ferramenta	Descrição
`gemini_chat`	Converse com o Gemini 3.1 Pro. Fundamentação da Pesquisa Google ativada por padrão. Suporta `thinking_level`
`gemini_deep_research`	Passagens de pesquisa fundamentada no Flash, sintetizadas em um relatório pelo 3.1 Pro. Padrão: 2 passagens
`gemini_list_models`	Lista os modelos que sua chave de API pode ver, ao vivo
`gemini_help`	Documentação para cada ferramenta sem sair do Claude
`gemini_prompt_assistant`	Orientação especializada para geração de imagens com nove sistemas de design de gráficos
`generate_image`	Geração de imagens com fundamentação de pesquisa opcional. Resolução total salva em disco
`edit_image`	Edite imagens com instruções em linguagem natural. Continuidade multi-turno via assinaturas de pensamento
`describe_image`	Descrições rápidas de imagens no Gemini 3.8 Flash
`analyze_image`	Extração e análise estruturada no Gemini 3.1 Pro
`load_image_from_path`	Leia um arquivo de imagem local e retorne base64 para qualquer ferramenta de imagem
`generate_video`	Geração de vídeo com Veo 3.1: 4 a 8 segundos em até 4K com áudio nativo
`generate_svg`	SVG pronto para produção: diagramas, ilustrações, ícones, visualizações de dados
`generate_landing_page`	Páginas de destino HTML autossuficientes com CSS e JS inline
`gemini_viewer_payload`	Interno. Os visualizadores inline usam isso para buscar seus dados de exibição; você nunca chamará isso

Referência de modelos

Verificado na API de modelos ao vivo em 22 de setembro de 2026. gemini_list_models informará o que sua chave pode ver hoje.

Modelo	Usado por	Notas
`gemini-3.1-pro-preview`	`gemini_chat`, `gemini_deep_research` (síntese), `analyze_image`, `generate_landing_page`	Padrão. Ainda é o modelo de raciocínio mais forte que o Google oferece, com ou sem rótulo de pré-visualização. Somente pago - sem camada gratuita
`gemini-3.8-flash`	`describe_image`, `gemini_deep_research` (passagens de pesquisa)	Padrão. O cavalo de batalha GA do Google em setembro de 2026; uma boa escolha de `gemini_chat` quando você quer velocidade
`gemini-3-flash-preview`	`generate_svg`	Padrão. Tem uma camada gratuita (página de preços do Google, 24 de setembro de 2026)
`gemini-3.7-flash`, `3.6`, `3.5`, `3.5-flash-lite`, `3.1-flash-lite`	qualquer ferramenta de texto	Versões GA Flash anteriores, todas aceitas
`gemini-3-pro-image`	`generate_image`, `edit_image`	Padrão. Nano Banana Pro, GA. 4K, texto real, edição conversacional
`gemini-3.1-flash-image`	`generate_image`, `edit_image`	Nano Banana 2, GA. Qualidade quase Pro, velocidade e preço Flash
`gemini-3.1-flash-lite-image`	`generate_image`	Nano Banana 2 Lite. Mais rápido e mais barato
`gemini-3-pro-image-preview`, `nano-banana-pro-preview`, `gemini-2.5-flash-image`	ferramentas de imagem	IDs mais antigos, ainda aceitos para que configurações existentes continuem funcionando
`veo-3.1-generate-preview`	`generate_video`	Padrão. Cinematográfico, áudio nativo, até 4K
`veo-3.1-lite-generate-preview`	`generate_video`	Mais barato e mais rápido na mesma API

Por que os padrões são o que são. Eu fiquei em dúvida sobre isso. O Gemini 3.8 Flash é GA e mais novo, mas o 3.1 Pro ainda é o que o Google chama de seu modelo de raciocínio mais forte, e raciocínio é o objetivo de gemini_chat e pesquisa aprofundada - então o Pro permanece como padrão nesses casos, e o Flash assume o trabalho mais leve de describe_image. Para imagens, o Nano Banana Pro saiu da pré-visualização e manteve sua vantagem de qualidade, então é o padrão; o Nano Banana 2 está disponível quando você prefere trocar um pouco de qualidade por muita velocidade. O modelo de vídeo Omni mais novo do Gemini usa uma API diferente, então ainda não está conectado.

Notas do Gemini 3: a temperatura é forçada para 1.0 em todos os modelos 3.x (exigência do Google, valores mais baixos causam loops). thinking_level se aplica a gemini_chat.

Orçamentos de tokens: max_tokens usa como padrão o teto de saída completo de cada modelo, conforme relatado ao vivo pela API de modelos (65.536 nos modelos de texto atuais do Gemini 3; o valor de 1M é o contexto de entrada). É um limite, não um consumo, então espaço não utilizado não custa nada. Valores abaixo de 4.096 são ignorados porque o pensamento do Gemini 3 consome orçamentos pequenos antes de você ver qualquer saída, o que parece exatamente um tempo limite, e valores acima do limite real do modelo são limitados.

Requisitos

Node.js 20.19+
Uma chave de API do Gemini do Google AI Studio
ffmpeg (opcional, para miniaturas de vídeo)

Licença

Apache-2.0