Gemini CLI

Integra-se com o CLI não oficial do Google Gemini, permitindo acesso a arquivos dentro de diretórios configurados.

GitHub
12
Experimente este MCPPatrocinado

Documentação

Gemini CLI MCP Server

CI codecov Python 3.10-3.13 License: MIT Ruff

Um servidor Model Context Protocol (MCP) que encapsula o Gemini CLI, permitindo que assistentes de IA como o Claude usem o Gemini para tarefas de pesquisa e análise.

Aviso: Esta é uma ferramenta não oficial, desenvolvida pela comunidade, que encapsula o Google Gemini CLI. Não é afiliada, endossada ou patrocinada pelo Google. Todas as marcas registradas, marcas de serviço e logotipos do Google e do Gemini são propriedade da Google LLC. Este projeto é licenciado sob a Licença MIT.

Importante: Esta ferramenta requer que o Gemini CLI esteja instalado e autenticado no seu sistema. Consulte a seção Pré-requisitos para detalhes.

Recursos

  • gemini_prompt: Envie prompts para o Gemini e receba respostas
  • gemini_research: Pesquise tópicos com contexto de arquivos opcional
  • gemini_analyze_code: Analise arquivos de código para revisões, explicações, otimizações, segurança ou testes
  • gemini_summarize: Resuma conteúdo de texto ou arquivos

Instalação

Início Rápido (Recomendado)

# Install from GitHub (latest)
uvx --from git+https://github.com/DiversioTeam/gemini-cli-mcp gemini-mcp

# Or from PyPI (when published)
uvx gemini-mcp

Instalação para Desenvolvimento

git clone https://github.com/DiversioTeam/gemini-cli-mcp
cd gemini-cli-mcp
uv sync
uv run gemini-mcp

Pré-requisitos

1. Python 3.10-3.13

Certifique-se de ter Python 3.10, 3.11, 3.12 ou 3.13 instalado. O projeto é testado em todas essas versões.

2. Instalação e Autenticação do Gemini CLI

Este servidor MCP requer que o Gemini CLI esteja instalado e autenticado:

  1. Instale o Gemini CLI: Siga as instruções oficiais de instalação para a sua plataforma
  2. Autentique: Execute gemini auth login e siga as instruções
  3. Verifique: Teste se funciona executando gemini -p "Hello, world!"

Se você vir um erro de autenticação, certifique-se de ter concluído o processo de login.

3. Cliente Compatível com MCP

Você precisará de um cliente compatível com MCP, como:

  • Claude Desktop
  • Outros assistentes de IA compatíveis com MCP

Uso

Configuração Inicial

Antes de executar o servidor, verifique sua configuração:

# Check if everything is configured correctly
gemini-mcp setup

Isso verificará:

  • Instalação do Gemini CLI
  • Status de autenticação
  • Configuração do ambiente

Se você vir erros de autenticação, execute:

gemini auth login

Executando o Servidor

# Method 1: Run from current directory (for development)
uv run gemini-mcp

# Method 2: Run using uvx from GitHub
uvx --from git+https://github.com/DiversioTeam/gemini-cli-mcp gemini-mcp

# Method 3: Run if installed globally
gemini-mcp

# With debug logging
LOG_LEVEL=DEBUG gemini-mcp

Configurando com o Claude Code (CLI)

Método 1: Usando a CLI (Recomendado)

# Install from GitHub (use -- separator for proper argument parsing)
claude mcp add gemini uvx -- --from git+https://github.com/DiversioTeam/gemini-cli-mcp.git gemini-mcp

# Or install from PyPI when published
claude mcp add gemini uvx -- gemini-mcp

Método 2: Configuração Manual

Adicione isso ao ~/.config/claude-code/mcp-settings.json:

{
  "servers": {
    "gemini": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/DiversioTeam/gemini-cli-mcp.git", "gemini-mcp"]
    }
  }
}

Configurando com o Claude Desktop

Adicione isso à configuração do seu Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "gemini": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/DiversioTeam/gemini-cli-mcp.git", "gemini-mcp"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Ferramentas Disponíveis

gemini_prompt

Envie um prompt simples para o Gemini.

Parâmetros:

  • prompt (obrigatório): O prompt a ser enviado
  • model (opcional): O modelo Gemini a ser usado (padrão: gemini-2.5-pro)
  • context (opcional): Contexto adicional para anexar ao prompt

gemini_research

Pesquise um tópico com contexto de arquivos opcional.

Parâmetros:

  • topic (obrigatório): O tópico ou pergunta de pesquisa
  • files (opcional): Lista de caminhos de arquivos para incluir como contexto
  • model (opcional): O modelo Gemini a ser usado

gemini_analyze_code

Analise arquivos de código para diversos fins.

Parâmetros:

  • files (obrigatório): Lista de arquivos de código a serem analisados
  • analysis_type (obrigatório): Tipo de análise - um de:
    • review: Revisão de código para problemas e melhorias
    • explain: Explicação detalhada do código
    • optimize: Sugestões de desempenho e manutenibilidade
    • security: Análise de vulnerabilidades de segurança
    • test: Sugestões de casos de teste
  • specific_question (opcional): Pergunta específica adicional
  • model (opcional): O modelo Gemini a ser usado

gemini_summarize

Resuma conteúdo de texto ou arquivos.

Parâmetros:

  • content (opcional): Conteúdo de texto a ser resumido
  • files (opcional): Arquivos a serem resumidos (alternativa ao conteúdo)
  • summary_type (opcional): Tipo de resumo - um de:
    • brief: Resumo de 2 a 3 frases (padrão)
    • detailed: Resumo abrangente
    • bullet_points: Formato de marcadores
    • executive: Resumo executivo para tomadores de decisão
  • model (opcional): O modelo Gemini a ser usado

Nota: content ou files deve ser fornecido.

Segurança

Este servidor MCP implementa várias medidas de segurança:

Controle de Acesso a Arquivos

  • Acesso a arquivos em sandbox: Por padrão, o acesso a arquivos é restrito ao diretório de trabalho atual
  • Validação de caminhos: Todos os caminhos de arquivo são validados para prevenir ataques de travessia de diretório
  • Diretórios permitidos configuráveis: Você pode especificar diretórios permitidos via:
    • Parâmetro do construtor: GeminiMCPServer(allowed_directories=["/path/to/safe/dir"])
    • Variável de ambiente: GEMINI_MCP_ALLOWED_DIRS=/path1:/path2:/path3

Sanitização de Entrada

  • Todas as entradas do usuário são devidamente sanitizadas antes de serem passadas para a CLI
  • A injeção de comandos é prevenida usando subprocess com listas de argumentos (nunca shell=True)
  • Os caminhos de arquivo são resolvidos e validados antes do uso

Boas Práticas

  • Sempre execute o servidor com as permissões mínimas necessárias
  • Atualize regularmente tanto o servidor MCP quanto o Gemini CLI
  • Monitore os logs para qualquer atividade suspeita

Desenvolvimento

Configurando o Ambiente de Desenvolvimento

  1. Clone o repositório:

    git clone https://github.com/DiversioTeam/gemini-cli-mcp.git
cd gemini-cli-mcp

  2. Instale as dependências de desenvolvimento:

    uv sync --all-extras --dev

  3. Instale os hooks de pre-commit:

    uv run pre-commit install

Testes Locais com o Claude Code

Você pode adicionar o servidor para testes locais com a CLI do Claude Code:

# Method 1: Add from local directory (for development)
claude mcp add gemini-local -- uv run gemini-mcp

# Method 2: Add from PyPI (when published)
claude mcp add gemini uvx -- gemini-mcp

# Method 3: Add from GitHub (development version)
claude mcp add gemini uvx -- --from git+https://github.com/DiversioTeam/gemini-cli-mcp.git gemini-mcp

# Then you can test the functionality immediately
# Example: Send prompts, research topics, analyze code, etc.

Executando Testes

# Run all tests with coverage
uv run pytest

# Run specific test file
uv run pytest tests/test_tools.py

# Run with verbose output
uv run pytest -v

Qualidade do Código

# Run linting
uv run ruff check .

# Run formatting
uv run ruff format .

# Run type checking
uv run mypy src/

# Run security checks
uv run ruff check --select S .

Solução de Problemas

Diagnóstico Rápido

Execute a verificação de configuração para diagnosticar problemas comuns:

gemini-mcp setup

Problemas Comuns

  1. "Gemini CLI não encontrado no PATH"

    • Certifique-se de que o Gemini CLI está instalado: which gemini
    • Adicione o Gemini ao seu PATH se necessário
    • Siga o guia de instalação para a sua plataforma

  2. Erros de autenticação

    • O servidor detectará se você não está autenticado
    • Execute gemini auth login para autenticar
    • Verifique se suas credenciais expiraram
    • A mensagem de erro o orientará sobre o que fazer

  3. Erros de acesso a arquivos

    • Verifique se os arquivos estão dentro dos diretórios permitidos
    • Use caminhos absolutos ou certifique-se de que os caminhos relativos estão corretos
    • Defina GEMINI_MCP_ALLOWED_DIRS para diretórios personalizados

  4. Erros de "Comando não encontrado"

    • Execute gemini-mcp setup para verificar sua instalação
    • Certifique-se de ter instalado o pacote: uv pip install -e .

Registro de Depuração

Ative o registro de depuração para ver informações detalhadas:

LOG_LEVEL=DEBUG gemini-mcp

Contribuindo

Aceitamos contribuições! Por favor:

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
  3. Faça suas alterações e adicione testes
  4. Certifique-se de que todos os testes passem e as verificações de qualidade do código sejam bem-sucedidas
  5. Faça commit das suas alterações (git commit -m 'Add amazing feature')
  6. Envie para o branch (git push origin feature/amazing-feature)
  7. Abra um Pull Request

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

Agradecimentos

  • Construído sobre o Model Context Protocol
  • Integra-se com o Gemini CLI do Google (integração não oficial)
  • Inspirado pelo ecossistema MCP e pela comunidade