Image for post Gemini CLI: agente de terminal con soporte MCP nativo

Gemini CLI: agente de terminal con soporte MCP nativo

Escrito por Sergio Márquez

TL;DR: Gemini CLI es el agente de IA para terminal de Google, open-source bajo licencia Apache 2.0, con soporte nativo para MCP (Model Context Protocol). Ofrece un tier gratuito funcional con hasta 1.000 peticiones diarias en Flash, un contexto de 1 millón de tokens y herramientas integradas como búsqueda web en tiempo real. Si usas Claude Code o Codex y buscas una alternativa con menor coste o mayor contexto para analizar codebases grandes, Gemini CLI merece atención seria.

El problema con el coste de los agentes de terminal

Usar Claude Code como agente principal en proyectos personales tiene un coste concreto: entre 20 y 200 €/mes dependiendo del tier y el uso. Para prototipos, proyectos de aprendizaje o equipos pequeños sin presupuesto asignado para herramientas de IA, ese rango puede ser difícil de justificar. Codex CLI resuelve parte del problema si ya pagas ChatGPT Plus, pero sigue sin ofrecer un tier realmente gratuito para API.

En este contexto, Gemini CLI de Google entra con una propuesta directa: código abierto, tier gratuito funcional, contexto de 1 millón de tokens y MCP integrado desde el primer día. Con más de 95.000 estrellas en GitHub desde su lanzamiento, la adopción ha sido rápida. Pero ¿cómo se comporta en la práctica?

¿Qué es Gemini CLI?

Gemini CLI es un agente de IA para terminal desarrollado por Google, publicado como proyecto open-source bajo licencia Apache 2.0. Permite interactuar con modelos Gemini directamente desde la línea de comandos, ejecutar herramientas integradas (operaciones de sistema de archivos, comandos shell, búsqueda web con Google Search) y extender sus capacidades mediante servidores MCP.

Su arquitectura sigue un bucle ReAct (Reason + Act): el modelo razona sobre la tarea, selecciona herramientas, ejecuta acciones y evalúa el resultado antes de continuar. Este patrón es equivalente al de Claude Code y permite completar tareas de múltiples pasos de forma autónoma, desde debuggear un endpoint hasta refactorizar un módulo entero.

MCP nativo: qué significa en la práctica

MCP (Model Context Protocol) es el estándar que permite a los agentes de IA conectarse a herramientas externas mediante un protocolo común. Claude Code popularizó su uso; Gemini CLI lo implementa de forma nativa desde su primera versión estable.

La diferencia práctica frente a soluciones anteriores es que puedes conectar cualquier servidor MCP existente sin adaptadores adicionales. Desde servidores de GitHub y Git hasta bases de datos o APIs internas, la configuración se define en un archivo JSON y el agente tiene acceso a esas herramientas desde la siguiente sesión. El CLI también incluye un sistema de hooks desde la versión v0.26.0, que funciona como middleware para el bucle agentico: puedes interceptar momentos del ciclo (antes de una acción, después de que el agente termina su turno) y ejecutar scripts personalizados sin modificar el código fuente del CLI.

Instalación y configuración inicial

Gemini CLI requiere Node.js 18 o superior. La instalación es directa, y puedes probarlo sin instalación permanente con npx:

# Ejecutar sin instalación permanente
npx @google/gemini-cli

# Instalación global (recomendada para uso habitual)
npm install -g @google/gemini-cli

# Verificar instalación
gemini --version

Al ejecutarlo por primera vez, el CLI solicita autenticación. Tienes dos opciones: usar tu cuenta de Google personal para acceder al tier gratuito, o configurar una API key de Google AI Studio para mayor control sobre modelos y límites:

# Autenticación con cuenta de Google (tier gratuito)
gemini auth login

# Alternativa: API key para mayor control
export GEMINI_API_KEY="tu-api-key-aqui"

GEMINI.md: el contexto del proyecto

Gemini CLI usa un archivo llamado GEMINI.md (o AGENT.md) en la raíz del proyecto para cargar contexto al inicio de cada sesión. Es el equivalente directo al CLAUDE.md de Claude Code: aquí defines las convenciones del proyecto, el stack técnico y las restricciones que el agente debe respetar.

# Proyecto: API de procesamiento de documentos

## Stack
- Python 3.12, FastAPI, Poetry
- Tests con pytest (cobertura mínima 80%)
- Linting con ruff, tipado con mypy strict

## Convenciones
- Imports ordenados: stdlib > third-party > local
- Variables de entorno en .env, nunca hardcodeadas
- Commits siguen Conventional Commits

## Tests
- Ejecutar pytest antes de marcar cualquier tarea como completa
- No modificar tests existentes para que pasen; corregir la implementación

Una diferencia importante respecto a Claude Code: Gemini CLI busca GEMINI.md únicamente en el directorio de trabajo actual, no en directorios padre. En monorepos, esto significa que debes tener el archivo en el directorio desde donde lanzas el CLI, o verificar con /show context que se cargó correctamente.

Configurar servidores MCP paso a paso

La configuración de MCP se define en ~/.gemini/settings.json para configuración global, o en .gemini/settings.json dentro del proyecto para configuración específica. Esta es la estructura base para un proyecto con acceso a Git y GitHub:

{
  "selectedAuthType": "gemini-api-key",
  "theme": "Default",
  "mcpServers": {
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/ruta/al/proyecto"
      ]
    }
  }
}

Tres puntos que evitan problemas habituales al configurar servidores MCP:

  • Las variables de entorno se referencian con $NOMBRE_VARIABLE, no se escriben directamente. Esto mantiene las credenciales fuera del archivo de configuración.
  • El CLI aplica sanitización automática: filtra variables cuyos nombres contienen patrones como *TOKEN*, *SECRET*, *KEY* o *AUTH*. Si un servidor MCP necesita una de esas variables, debes declararla explícitamente en el bloque env; de lo contrario, el servidor arranca sin ella y los errores no son obvios.
  • Para verificar que los servidores están activos y qué herramientas exponen, usa el comando /mcp dentro del CLI. El estado detallado de cada servidor está en /mcp status.

También puedes conectar servidores MCP remotos mediante HTTP o SSE, con soporte para OAuth 2.0. Esto abre la puerta a integrar servidores MCP hospedados en tu infraestructura sin necesidad de tenerlos localmente.

Comparativa: Gemini CLI, Claude Code y Codex CLI

A febrero de 2026, los tres agentes de terminal principales tienen perfiles distintos. Esta tabla recoge los puntos más relevantes para elegir según el contexto de trabajo:

Criterio Gemini CLI Claude Code Codex CLI
Modelo base Gemini 2.5 Pro / Flash Claude Opus 4.6 GPT-5 Codex / codex-mini
Contexto 1M tokens 200K (con compactación) 192K tokens
Tier gratuito Sí (100 req/día Pro, 1.000 Flash) No Incluido con ChatGPT Plus
Open source Sí (Apache 2.0) No Sí (MIT)
MCP nativo Sí Sí Sí
Búsqueda web integrada Sí (Google Search) Via MCP No nativa
Sandbox de ejecución Parcial Configurable Sí (nativo)
Hooks de ciclo agentico Sí (v0.26.0+) Sí Limitado
Integración CI/CD Parcial Parcial Sí (GitHub Actions nativo)

En pruebas comparativas publicadas en los primeros meses de 2026, Claude Code completó una tarea de refactorización de múltiples archivos en 1 hora 17 minutos con un coste aproximado de 4,40 €, mientras que Gemini CLI tardó 2 horas 2 minutos y consumió alrededor de 6,50 € en tokens. La diferencia en coste absoluto es pequeña; la diferencia en tiempo puede importar según el contexto. Para tareas de análisis, planning o revisión de codebases grandes, la ventana de 1M tokens de Gemini CLI es una ventaja real.

Caso práctico: revisión de PRs con GitHub MCP

Un flujo directo: usar Gemini CLI con el servidor MCP de GitHub para revisar pull requests desde la terminal. Primero, configura el token en tu entorno:

export GITHUB_TOKEN="ghp_tu_token_aqui"

Con el servidor GitHub activo en settings.json, las consultas son naturales:

# Listar PRs abiertos
gemini "Lista los PRs abiertos del repositorio miorg/mi-api y dame un resumen de los cambios"

# Revisar un PR específico
gemini "Revisa el PR #42 del repositorio miorg/mi-api, señala posibles problemas de seguridad en los endpoints añadidos y sugiere mejoras"

# Flujo de desarrollo con Python
gemini "Revisa los archivos modificados en el working tree, ejecuta pytest y dame el resumen de cobertura"

El agente usa las herramientas del servidor MCP para obtener la información, la procesa con el modelo y devuelve el análisis. Para repositorios de tamaño mediano, la ventana de 1M tokens permite cargar el historial completo de cambios sin truncar. Para repositorios más grandes, sigue siendo necesario acotar el contexto manualmente.

Para proyectos TypeScript, el flujo es análogo. Añadir un servidor MCP de sistema de archivos y un servidor de Node.js permite al agente ejecutar scripts, leer la salida de tsc y proponer correcciones en el mismo turno.

En producción

Varios aspectos cambian cuando pasas de explorar Gemini CLI a integrarlo en un flujo de trabajo diario.

Límites reales del tier gratuito: Los 100 requests/día de Gemini 2.5 Pro parecen suficientes hasta que usas el agente en modo autónomo. En ese modo, una sola instrucción puede generar entre 5 y 15 requests al modelo internamente. Si superas el límite, el CLI cae automáticamente a Gemini 2.5 Flash (hasta 1.000 requests/día), que tiene capacidades algo menores pero cubre la mayoría de tareas de desarrollo. Para uso profesional continuado, una API key de Google AI Studio con un presupuesto de entre 5 y 20 €/mes es más predecible. A febrero de 2026, Gemini 2.5 Pro cuesta aproximadamente 1,15 €/millón de tokens de entrada y 9,20 €/millón de tokens de salida. Los precios pueden cambiar; consulta la documentación oficial de Google AI Studio antes de planificar el presupuesto.

Sanitización de MCP y variables de entorno: El CLI filtra por defecto las variables que contienen KEY, TOKEN, SECRET, PASSWORD o AUTH cuando lanza procesos MCP. Si un servidor necesita acceso a una de esas variables, la omisión del bloque env provoca errores silenciosos difíciles de rastrear. La regla es simple: declara explícitamente cualquier variable que el servidor necesite.

Sesiones largas y acumulación de contexto: Con 1M tokens disponibles, la tentación es dejar que el contexto crezca sin límites. En sesiones de más de dos horas con muchas iteraciones, el modelo puede priorizar información temprana de la sesión sobre instrucciones más recientes. El comando /clear reinicia el contexto sin cerrar la sesión, lo que suele mejorar la coherencia en tareas largas.

Actualizaciones frecuentes: Al ser open-source con ciclos de release semanales (versiones estables cada martes), Gemini CLI recibe cambios que pueden alterar comportamientos existentes. Si lo integras en flujos de CI/CD o scripts automatizados, fijar la versión con npm install -g @google/gemini-cli@VERSION evita sorpresas.

Hooks para control del bucle agentico: Desde v0.26.0, puedes configurar hooks que interceptan momentos del ciclo: antes de que el agente ejecute una acción, después de que termina su turno, o ante determinados eventos. Esto permite implementar patrones como el "Ralph loop" (el agente continúa automáticamente hasta completar la tarea) o añadir validaciones antes de que se ejecuten comandos destructivos.

Errores comunes y depuración

Error: el servidor MCP no responde al iniciar la sesión
Causa: el binario del servidor no está instalado o no está en el PATH del sistema.
Solución: verifica con which uvx o npx --version. Instala las dependencias del servidor antes de configurarlo en settings.json. Si usas uvx, asegúrate de tener uv instalado.

Error: variable de entorno no disponible dentro del servidor MCP
Causa: el CLI sanitiza variables sensibles por defecto cuando lanza procesos MCP.
Solución: declara la variable explícitamente en el bloque env del servidor en settings.json usando la sintaxis "MI_VAR": "$MI_VAR". Las variables declaradas explícitamente no se filtran.

Error: límite de rate excedido (HTTP 429)
Causa: el tier gratuito de Gemini 2.5 Pro permite solo 5 requests/minuto y 100/día.
Solución: configura una API key de Google AI Studio para límites más amplios. Para forzar el uso de Flash desde el inicio, usa --model gemini-2.5-flash al lanzar el CLI.

GEMINI.md no se carga en el inicio de sesión
Causa: el archivo no está en el directorio de trabajo actual desde donde se lanza el CLI.
Solución: usa el comando /show context dentro del CLI para verificar qué archivos de contexto cargó el agente. Mueve GEMINI.md al directorio raíz del proyecto o lanza el CLI desde ese directorio.

Preguntas frecuentes

¿Gemini CLI puede reemplazar a Claude Code para uso diario?

Depende del caso de uso. Para planning, revisión de documentación o análisis de codebases grandes, Gemini CLI es competitivo y más económico. Para tareas de implementación autónoma complejas donde importa la velocidad, Claude Code sigue siendo más rápido. Un patrón que aparece con frecuencia en equipos que optimizan costes es usar Gemini para planning y contexto inicial, y Claude Code para implementación.

¿Los servidores MCP configurados para Claude Code funcionan con Gemini CLI?

Sí. El protocolo MCP es estándar, por lo que cualquier servidor compatible funciona con ambos agentes sin modificaciones. La configuración difiere: Gemini usa .gemini/settings.json y Claude Code usa .claude/settings.json, pero los servidores son interoperables. Puedes tener los mismos servidores MCP activos en los dos agentes a la vez.

¿Cuánto cuesta realmente usar Gemini CLI en un proyecto de desarrollo?

El tier gratuito cubre necesidades básicas: hasta 100 peticiones diarias con Gemini 2.5 Pro y hasta 1.000 con Flash. Para uso profesional con API key, entre 5 y 20 €/mes es un rango realista en proyectos individuales de desarrollo moderado. En escenarios de uso intensivo con contextos largos, los costes pueden superar ese rango. Configura cuotas en Google Cloud Console desde el inicio para tener visibilidad y evitar sorpresas.

Conclusión

Gemini CLI entra al espacio de agentes de terminal con una propuesta clara: código abierto, tier gratuito real, contexto de 1 millón de tokens y MCP integrado desde el primer día. No supera a Claude Code en velocidad de ejecución de tareas complejas, pero para análisis de codebases, revisión de código y flujos donde el presupuesto importa, es una alternativa que merece evaluarse.

La interoperabilidad con servidores MCP existentes reduce la fricción de adopción. Si ya tienes configurados servidores MCP para Claude Code o Codex, puedes reutilizarlos con Gemini CLI con cambios mínimos. El sistema de hooks añadido en v0.26.0 amplía las posibilidades de personalización sin necesidad de modificar el código fuente del CLI.

El punto de partida es sencillo: instala el CLI, crea un GEMINI.md con el contexto del proyecto y añade un servidor MCP de Git. Con eso ya tienes un agente funcional con acceso al historial del repositorio. A partir de ahí, el ecosistema de servidores MCP existente hace el resto.

¿Has probado Gemini CLI en algún proyecto o lo comparas directamente con Claude Code en tu flujo diario? Cuéntame en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo analizo Dify como plataforma de workflows agenticos, otra herramienta open-source que acumula tracción importante en la comunidad.

Volver al blog