Gemini Bridge

Un servidor MCP (Model Context Protocol) ligero que permite a los asistentes de codificación de IA interactuar con la IA Gemini de Google a través de la CLI oficial. Funciona con Claude Code, Cursor, VS Code y otros clientes compatibles con MCP. Diseñado para la simplicidad, la fiabilidad y una integración fluida.

✨ Características

• Integración directa con Gemini CLI: Costes de API cero utilizando la CLI oficial de Gemini

• Tres herramientas MCP: Consultas básicas, análisis de archivos y capacidades de búsqueda web

• Operación sin estado: Sin sesiones, almacenamiento en caché ni gestión compleja de estados

• Listo para producción: Manejo robusto de errores con tiempos de espera configurables de 60 segundos

• Dependencias mínimas: Solo requiere mcp>=1.0.0 y Gemini CLI

• Despliegue sencillo: Soporte tanto para uvx como para la instalación tradicional con pip

• Compatibilidad universal con MCP: Funciona con cualquier asistente de codificación de IA compatible con MCP

• Python moderno: Utiliza pathlib y sugerencias de tipo modernas (Python 3.10+)

Related MCP server: Globalping

🚀 Inicio rápido

Requisitos previos

1. Instalar Gemini CLI:

   npm install -g @google/gemini-cli

2. Autenticarse con Gemini:

   gemini auth login

3. Verificar la instalación:

   gemini --version

Instalación

🎯 Recomendado: Instalación mediante PyPI

# Install from PyPI
pip install gemini-bridge

# Add to Claude Code with uvx (recommended)
claude mcp add gemini-bridge -s user -- uvx gemini-bridge

Alternativa: Desde el código fuente

# Clone the repository
git clone https://github.com/shelakh/gemini-bridge.git
cd gemini-bridge

# Build and install locally
uvx --from build pyproject-build
pip install dist/*.whl

# Add to Claude Code
claude mcp add gemini-bridge -s user -- uvx gemini-bridge

Instalación para desarrollo

# Clone and install in development mode
git clone https://github.com/shelakh/gemini-bridge.git
cd gemini-bridge
pip install -e .

# Add to Claude Code (development)
claude mcp add gemini-bridge-dev -s user -- python -m src

🌐 Soporte multi-cliente

Gemini Bridge funciona con cualquier asistente de codificación de IA compatible con MCP: el mismo servidor admite múltiples clientes a través de diferentes métodos de configuración.

Clientes MCP compatibles

• Claude Code ✅ (Predeterminado)

• Cursor ✅

• VS Code ✅

• Windsurf ✅

• Cline ✅

• Void ✅

• Cherry Studio ✅

• Augment ✅

• Roo Code ✅

• Zencoder ✅

• Cualquier cliente compatible con MCP ✅

Ejemplos de configuración

# Recommended installation
claude mcp add gemini-bridge -s user -- uvx gemini-bridge

# Development installation
claude mcp add gemini-bridge-dev -s user -- python -m src

Configuración global (~/.cursor/mcp.json):

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {}
    }
  }
}

Específica del proyecto (.cursor/mcp.json en su proyecto):

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {}
    }
  }
}

Vaya a: Settings → Cursor Settings → MCP → Add new global MCP server

Configuración (.vscode/mcp.json en su espacio de trabajo):

{
  "servers": {
    "gemini-bridge": {
      "type": "stdio",
      "command": "uvx",
      "args": ["gemini-bridge"]
    }
  }
}

Alternativa: A través de extensiones

1. Abra la vista de Extensiones (Ctrl+Shift+X)

2. Busque extensiones MCP

3. Añada un servidor personalizado con el comando: uvx gemini-bridge

Añada a su configuración MCP de Windsurf:

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {}
    }
  }
}

1. Abra Cline y haga clic en MCP Servers en la navegación superior

2. Seleccione la pestaña Installed → Advanced MCP Settings

3. Añada a cline_mcp_settings.json:

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {}
    }
  }
}

Vaya a: Settings → MCP → Add MCP Server

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {}
    }
  }
}

1. Navegue a Settings → MCP Servers → Add Server

2. Rellene los detalles del servidor:

   • Name: gemini-bridge

   • Type: STDIO

   • Command: uvx

   • Arguments: ["gemini-bridge"]

3. Guarde la configuración

Usando la interfaz de usuario:

1. Haga clic en el menú hamburguesa → Settings → Tools

2. Haga clic en el botón + Add MCP

3. Introduzca el comando: uvx gemini-bridge

4. Nombre: Gemini Bridge

Configuración manual:

"augment.advanced": { 
  "mcpServers": [ 
    { 
      "name": "gemini-bridge", 
      "command": "uvx", 
      "args": ["gemini-bridge"],
      "env": {}
    }
  ]
}

1. Vaya a Settings → MCP Servers → Edit Global Config

2. Añada a mcp_settings.json:

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {}
    }
  }
}

1. Vaya al menú de Zencoder (...) → Tools → Add Custom MCP

2. Añada la configuración:

{
  "command": "uvx",
  "args": ["gemini-bridge"],
  "env": {}
}

3. Pulse el botón Install

Para instalaciones basadas en pip:

{
  "command": "gemini-bridge",
  "args": [],
  "env": {}
}

Para desarrollo/pruebas locales:

{
  "command": "python",
  "args": ["-m", "src"],
  "env": {},
  "cwd": "/path/to/gemini-bridge"
}

Para instalación estilo npm (si es necesario):

{
  "command": "npx",
  "args": ["gemini-bridge"],
  "env": {}
}

Uso universal

Una vez configurado con cualquier cliente, utilice las mismas dos herramientas:

1. Hacer preguntas generales: "¿Qué patrones de autenticación se utilizan en esta base de código?"

2. Analizar archivos específicos: "Revisa estos archivos de autenticación en busca de problemas de seguridad"

La implementación del servidor es idéntica: ¡solo difiere la configuración del cliente!

⚙️ Configuración

Configuración del tiempo de espera (Timeout)

Por defecto, Gemini Bridge utiliza un tiempo de espera de 60 segundos para todas las operaciones de la CLI. Para consultas más largas (archivos grandes, análisis complejos), puede configurar un tiempo de espera personalizado utilizando la variable de entorno GEMINI_BRIDGE_TIMEOUT.

Ejemplos de configuración:

# Add with custom timeout (120 seconds)
claude mcp add gemini-bridge -s user --env GEMINI_BRIDGE_TIMEOUT=120 -- uvx gemini-bridge

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {
        "GEMINI_BRIDGE_TIMEOUT": "120"
      }
    }
  }
}

Opciones de tiempo de espera:

• Predeterminado: 60 segundos (si no se configura)

• Rango: Cualquier número entero positivo (segundos)

• Anulación por llamada: Proporcione timeout_seconds a cualquiera de las herramientas para extensiones puntuales

• Recomendado: 120-300 segundos para análisis de archivos grandes

• Valores no válidos: Se vuelve a los 60 segundos con una advertencia

🛠️ Herramientas disponibles

consult_gemini

Puente directo de CLI para consultas simples.

Parámetros:

• query (string): La pregunta o prompt para enviar a Gemini

• directory (string): Directorio de trabajo para la consulta

• model (string, opcional): Modelo a utilizar - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite", o "auto" (predeterminado: "flash")

• timeout_seconds (int, opcional): Anular el tiempo de espera de ejecución para esta solicitud

Ejemplo:

consult_gemini(
    query="Find authentication patterns in this codebase",
    directory="/path/to/project",
    model="flash"
)

consult_gemini_with_files

Puente de CLI con archivos adjuntos para un análisis detallado.

Parámetros:

• query (string): La pregunta o prompt para enviar a Gemini

• directory (string): Directorio de trabajo para la consulta

• files (list): Lista de rutas de archivos relativas al directorio

• model (string, opcional): Modelo a utilizar - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite", o "auto" (predeterminado: "flash")

• timeout_seconds (int, opcional): Anular el tiempo de espera de ejecución para esta solicitud

• mode (string, opcional): Ya sea "inline" (predeterminado) para transmitir el contenido del archivo o "at_command" para dejar que la CLI de Gemini resuelva las referencias @path por sí misma

Ejemplo:

consult_gemini_with_files(
    query="Analyze these auth files and suggest improvements",
    directory="/path/to/project",
    files=["src/auth.py", "src/models.py"],
    model="pro",
    timeout_seconds=180
)

Consejo: Al escanear árboles grandes, cambie a mode="at_command" para que la CLI de Gemini maneje el globbing y el truncamiento de archivos de forma nativa.

web_search

Realice consultas a Gemini con contexto de búsqueda web. Utiliza la búsqueda web automática de la CLI de Gemini cuando el modelo determina que es necesaria. Funcionalidad de mejor esfuerzo: no garantizada para todas las consultas.

Parámetros:

• query (string): Consulta de búsqueda o pregunta para buscar en la web

• directory (string): Directorio de trabajo para la ejecución del comando

• model (string, opcional): Modelo a utilizar - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite", o "auto" (predeterminado: "flash")

• timeout_seconds (int, opcional): Anular el tiempo de espera de ejecución para esta solicitud

Ejemplo:

web_search(
    query="latest Python version and new features",
    model="flash"
)

📋 Ejemplos de uso

Análisis de código básico

# Simple research query
consult_gemini(
    query="What authentication patterns are used in this project?",
    directory="/Users/dev/my-project"
)

Revisión detallada de archivos

# Analyze specific files
consult_gemini_with_files(
    query="Review these files and suggest security improvements",
    directory="/Users/dev/my-project",
    files=["src/auth.py", "src/middleware.py"],
    model="pro"
)

Análisis de múltiples archivos

# Compare multiple implementation files
consult_gemini_with_files(
    query="Compare these database implementations and recommend the best approach",
    directory="/Users/dev/my-project",
    files=["src/db/postgres.py", "src/db/sqlite.py", "src/db/redis.py"],
    mode="at_command"
)

Búsqueda web

# Get current information from the web
web_search(
    query="latest Python version and new features in 3.13",
    model="flash"
)

Salvaguardas para archivos grandes

• Las transferencias en línea tienen un límite de ~256 KB por archivo y ~512 KB por solicitud para evitar bloqueos.

• Los archivos de gran tamaño se truncan a fragmentos de inicio/fin con una advertencia en la respuesta MCP.

• Ajuste los límites con variables de entorno (GEMINI_BRIDGE_MAX_INLINE_TOTAL_BYTES, etc.) o prefiera mode="at_command" para cargas útiles más grandes.

🏗️ Arquitectura

Diseño central

• CLI-First: Llamadas directas de subprocesos al comando gemini

• Sin estado: Cada llamada a la herramienta es independiente sin estado de sesión

• Tiempo de espera adaptativo: Predeterminado a 60 segundos pero anulable por solicitud o mediante variable de entorno

• Barandillas de archivos adjuntos: El modo en línea impone límites ligeros; el modo @ delega en las herramientas de la CLI de Gemini

• Manejo simple de errores: Mensajes de error claros con un enfoque de fallo rápido

Estructura del proyecto

gemini-bridge/
├── src/
│   ├── __init__.py              # Entry point
│   ├── __main__.py              # Module execution entry point
│   └── mcp_server.py            # Main MCP server implementation
├── .github/                     # GitHub templates and workflows
├── pyproject.toml              # Python package configuration
├── README.md                   # This file
├── CONTRIBUTING.md             # Contribution guidelines
├── CODE_OF_CONDUCT.md          # Community standards
├── SECURITY.md                 # Security policies
├── CHANGELOG.md               # Version history
└── LICENSE                    # MIT license

🔧 Desarrollo

Pruebas locales

# Install in development mode
pip install -e .

# Run directly
python -m src

# Test CLI availability
gemini --version

Integración con Claude Code

El servidor se integra automáticamente con Claude Code cuando se configura correctamente a través del protocolo MCP.

🔍 Solución de problemas

CLI no disponible

# Install Gemini CLI
npm install -g @google/gemini-cli

# Authenticate
gemini auth login

# Test
gemini --version

Problemas de conexión

• Verifique que la CLI de Gemini esté correctamente autenticada

• Compruebe la conectividad de red

• Asegúrese de que la configuración MCP de Claude Code sea correcta

• Compruebe que el comando gemini esté en su PATH

Mensajes de error comunes

• "CLI not available": La CLI de Gemini no está instalada o no está en el PATH

• "Authentication required": Ejecute gemini auth login

• "Timeout after 60 seconds": La consulta tardó demasiado, intente dividirla en partes más pequeñas

🤝 Contribución

¡Damos la bienvenida a las contribuciones de la comunidad! Por favor, lea nuestras Directrices de contribución para obtener detalles sobre cómo empezar.

Guía rápida de contribución

1. Haga un fork del repositorio

2. Cree una rama de características

3. Realice sus cambios

4. Añada pruebas si corresponde

5. Envíe una solicitud de extracción (pull request)

📄 Licencia

Este proyecto está bajo la Licencia MIT: consulte el archivo LICENSE para obtener más detalles.

🔄 Historial de versiones

Consulte CHANGELOG.md para obtener un historial de versiones detallado.

🆘 Soporte

• Problemas: Informe de errores o solicite funciones a través de GitHub Issues

• Discusiones: Únase a la discusión de la comunidad

• Documentación: Se puede crear documentación adicional en el directorio docs/

Enfoque: Un puente simple y fiable entre Claude Code y Gemini AI a través de la CLI oficial.