Gemini CLI

Se integra con el CLI no oficial de Google Gemini, permitiendo el acceso a archivos dentro de directorios configurados.

GitHub
12
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Gemini CLI

CI codecov Python 3.10-3.13 License: MIT Ruff

Un servidor de Protocolo de Contexto de Modelo (MCP) que envuelve la CLI de Gemini, permitiendo que asistentes de IA como Claude utilicen Gemini para tareas de investigación y análisis.

Aviso: Esta es una herramienta no oficial, desarrollada por la comunidad, que envuelve la CLI de Google Gemini. No está afiliada, respaldada ni patrocinada por Google. Todas las marcas comerciales, marcas de servicio y logotipos de Google y Gemini son propiedad de Google LLC. Este proyecto está licenciado bajo la Licencia MIT.

Importante: Esta herramienta requiere que tengas la CLI de Gemini instalada y autenticada en tu sistema. Consulta la sección Requisitos previos para más detalles.

Características

  • gemini_prompt: Envía indicaciones a Gemini y recibe respuestas
  • gemini_research: Investiga temas con contexto de archivos opcional
  • gemini_analyze_code: Analiza archivos de código para revisiones, explicaciones, optimizaciones, seguridad o pruebas
  • gemini_summarize: Resume contenido de texto o archivos

Instalación

Inicio 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

Instalación para desarrollo

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

Requisitos previos

1. Python 3.10-3.13

Asegúrate de tener instalado Python 3.10, 3.11, 3.12 o 3.13. El proyecto está probado en todas estas versiones.

2. Instalación y autenticación de la CLI de Gemini

Este servidor MCP requiere que la CLI de Gemini esté instalada y autenticada:

  1. Instala la CLI de Gemini: Sigue las instrucciones de instalación oficiales para tu plataforma
  2. Autentícate: Ejecuta gemini auth login y sigue las indicaciones
  3. Verifica: Prueba que funciona ejecutando gemini -p "Hello, world!"

Si ves un error de autenticación, asegúrate de haber completado el proceso de inicio de sesión.

3. Cliente compatible con MCP

Necesitarás un cliente compatible con MCP, como:

  • Claude Desktop
  • Otros asistentes de IA compatibles con MCP

Uso

Configuración inicial

Antes de ejecutar el servidor, verifica tu configuración:

# Check if everything is configured correctly
gemini-mcp setup

Esto comprobará:

  • La instalación de la CLI de Gemini
  • El estado de autenticación
  • La configuración del entorno

Si ves errores de autenticación, ejecuta:

gemini auth login

Ejecutar el 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

Configuración con Claude Code (CLI)

Método 1: Usando la 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: Configuración manual

Añade esto a ~/.config/claude-code/mcp-settings.json:

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

Configuración con Claude Desktop

Añade esto a tu configuración de 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"
      }
    }
  }
}

Herramientas disponibles

gemini_prompt

Envía una indicación simple a Gemini.

Parámetros:

  • prompt (obligatorio): La indicación a enviar
  • model (opcional): El modelo de Gemini a utilizar (predeterminado: gemini-2.5-pro)
  • context (opcional): Contexto adicional para anteponer a la indicación

gemini_research

Investiga un tema con contexto de archivos opcional.

Parámetros:

  • topic (obligatorio): El tema o pregunta de investigación
  • files (opcional): Lista de rutas de archivos para incluir como contexto
  • model (opcional): El modelo de Gemini a utilizar

gemini_analyze_code

Analiza archivos de código para diversos propósitos.

Parámetros:

  • files (obligatorio): Lista de archivos de código a analizar
  • analysis_type (obligatorio): Tipo de análisis — uno de:
    • review: Revisión de código para problemas y mejoras
    • explain: Explicación detallada del código
    • optimize: Sugerencias de rendimiento y mantenibilidad
    • security: Análisis de vulnerabilidades de seguridad
    • test: Sugerencias de casos de prueba
  • specific_question (opcional): Pregunta específica adicional
  • model (opcional): El modelo de Gemini a utilizar

gemini_summarize

Resume contenido de texto o archivos.

Parámetros:

  • content (opcional): Contenido de texto a resumir
  • files (opcional): Archivos a resumir (alternativa al contenido)
  • summary_type (opcional): Tipo de resumen — uno de:
    • brief: Resumen de 2-3 frases (predeterminado)
    • detailed: Resumen exhaustivo
    • bullet_points: Formato de viñetas
    • executive: Resumen ejecutivo para tomadores de decisiones
  • model (opcional): El modelo de Gemini a utilizar

Nota: Se debe proporcionar content o files.

Seguridad

Este servidor MCP implementa varias medidas de seguridad:

Control de acceso a archivos

  • Acceso a archivos en entorno aislado: Por defecto, el acceso a archivos está restringido al directorio de trabajo actual
  • Validación de rutas: Todas las rutas de archivos se validan para prevenir ataques de recorrido de directorios
  • Directorios permitidos configurables: Puedes especificar directorios permitidos mediante:
    • Parámetro del constructor: GeminiMCPServer(allowed_directories=["/path/to/safe/dir"])
    • Variable de entorno: GEMINI_MCP_ALLOWED_DIRS=/path1:/path2:/path3

Saneamiento de entradas

  • Todas las entradas del usuario se sanean adecuadamente antes de pasarse a la CLI
  • La inyección de comandos se previene usando subprocess con listas de argumentos (nunca shell=True)
  • Las rutas de archivos se resuelven y validan antes de su uso

Buenas prácticas

  • Ejecuta siempre el servidor con los permisos mínimos necesarios
  • Actualiza regularmente tanto el servidor MCP como la CLI de Gemini
  • Supervisa los registros para detectar cualquier actividad sospechosa

Desarrollo

Configuración del entorno de desarrollo

  1. Clona el repositorio:

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

  2. Instala las dependencias de desarrollo:

    uv sync --all-extras --dev

  3. Instala los hooks de pre-commit:

    uv run pre-commit install

Pruebas locales con Claude Code

Puedes añadir el servidor para pruebas locales con la CLI de 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.

Ejecutar pruebas

# 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

Calidad del 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 .

Solución de problemas

Diagnóstico rápido

Ejecuta la comprobación de configuración para diagnosticar problemas comunes:

gemini-mcp setup

Problemas comunes

  1. "Gemini CLI no encontrada en PATH"

    • Asegúrate de que la CLI de Gemini esté instalada: which gemini
    • Añade Gemini a tu PATH si es necesario
    • Sigue la guía de instalación para tu plataforma

  2. Errores de autenticación

    • El servidor detectará si no estás autenticado
    • Ejecuta gemini auth login para autenticarte
    • Comprueba si tus credenciales han caducado
    • El mensaje de error te guiará sobre qué hacer

  3. Errores de acceso a archivos

    • Comprueba que los archivos estén dentro de los directorios permitidos
    • Usa rutas absolutas o asegúrate de que las rutas relativas sean correctas
    • Establece GEMINI_MCP_ALLOWED_DIRS para directorios personalizados

  4. Errores de "Comando no encontrado"

    • Ejecuta gemini-mcp setup para comprobar tu instalación
    • Asegúrate de haber instalado el paquete: uv pip install -e .

Registro de depuración

Habilita el registro de depuración para ver información detallada:

LOG_LEVEL=DEBUG gemini-mcp

Contribuciones

¡Agradecemos las contribuciones! Por favor:

  1. Haz un fork del repositorio
  2. Crea una rama de funcionalidad (git checkout -b feature/amazing-feature)
  3. Realiza tus cambios y añade pruebas
  4. Asegúrate de que todas las pruebas pasen y los controles de calidad del código tengan éxito
  5. Confirma tus cambios (git commit -m 'Add amazing feature')
  6. Sube la rama (git push origin feature/amazing-feature)
  7. Abre una Solicitud de Extracción (Pull Request)

Licencia

Este proyecto está licenciado bajo la Licencia MIT — consulta el archivo LICENCIA para más detalles.

Agradecimientos

  • Construido sobre el Protocolo de Contexto de Modelo
  • Se integra con la CLI de Gemini de Google (integración no oficial)
  • Inspirado por el ecosistema MCP y la comunidad