mcp-google-sheets

Google Sheets MCP

Inglés | Русский

A1 Google Sheets MCP permite que una aplicación de IA trabaje con Google Sheets en lenguaje natural. Busca una hoja de cálculo, lee sus datos, escribe y agrega filas, da forma a hojas y formato, crea gráficos y comparte el resultado.

Utiliza la API de Google Sheets con tu cuenta de Google. Separa la lectura de la escritura, mantiene explícitas las operaciones destructivas y aclara los límites de la API de Sheets en lugar de dar a entender que cualquier tarea de hoja de cálculo es posible.

• 26 herramientas. Busca y crea hojas de cálculo, lee y escribe rangos, gestiona hojas, formato, validación de datos, rangos protegidos, formatos condicionales, tablas estructuradas, gráficos y acceso.
• Se conecta desde la conversación. Di "conectar Google Sheets": el servidor te guía a través del cliente OAuth, captura la redirección de Google en 127.0.0.1 con PKCE y guarda los tokens él mismo — sin archivos de configuración, sin reinicios.
• Las escrituras son deliberadas. Una escritura nunca se reproduce después de un fallo ambiguo — una anexión reproducida duplicaría filas — y las herramientas destructivas están marcadas para que tu cliente de IA pueda preguntar primero.
• Solo Sheets. Drive es una dependencia interna únicamente para la búsqueda y el uso compartido de hojas de cálculo; no hay ninguna herramienta genérica de Drive, y raw_request no puede acceder a Drive.
• Ámbitos de Google mínimos. spreadsheets cubre todas las herramientas de Sheets; se necesita un ámbito de Drive solo para la búsqueda y el uso compartido de hojas de cálculo.

Comienza con una pregunta de solo lectura:

Encuentra la hoja de cálculo del presupuesto trimestral y resume qué contiene cada una de sus hojas.

Conectar el servidor · Explorar casos de uso · Abrir documentación técnica

Véalo funcionar en un minuto

Tú: Muéstrame la estructura de la hoja de cálculo del informe de ventas — sus hojas, sus tamaños y filas congeladas.

Asistente: Muestra las hojas con sus tamaños, encabezados congelados y los objetos que contienen. No cambia nada.

Tú: Prepara una hoja "Marzo" como copia de "Febrero" y borra los números, conservando el diseño.

Asistente: Muestra el plan — duplicar la hoja, renombrarla y borrar los rangos de datos — y luego pide confirmación antes de cambiar nada.

Tú: Confirmo.

Asistente: Duplica la hoja y borra los valores. El formato, la validación de datos y las filas congeladas se mantienen.

Contenido

• Inicio rápido
• Qué puedes pedirle que haga
• Cómo cambia una hoja de cálculo
• Qué puede cambiar
• Obtener acceso
• Configuración
• Datos, límites y trabajo en segundo plano
• Documentación técnica
• Soporte

Inicio rápido

Necesitas Node.js 20+ y una cuenta de Google. No se requieren credenciales al instalar — el servidor se conecta desde la conversación.

1. Añade el servidor a tu aplicación de IA.
2. Di "conectar Google Sheets": el asistente te guía a través de la creación del cliente OAuth y la aprobación del acceso sin editar archivos de configuración.
3. Haz la pregunta de solo lectura anterior.

codex mcp add google-sheets \
  -- npx -y @a1-x-tech/mcp-google-sheets@latest

codex mcp list

claude mcp add \
  --transport stdio --scope user google-sheets \
  -- npx -y @a1-x-tech/mcp-google-sheets@latest

claude mcp list

{
  "mcpServers": {
    "google-sheets": {
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-sheets@latest"]
    }
  }
}

{
  "mcpServers": {
    "google-sheets": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-sheets@latest"]
    }
  }
}

{
  "servers": {
    "google-sheets": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-sheets@latest"]
    }
  }
}

Qué puedes pedirle que haga

Encontrar y leer datos

• Encuentra la hoja de cálculo más reciente con "presupuesto" en el nombre y muestra su estructura.
• Lee 'Q3'!A1:F50 y resume los totales.
• Muestra las fórmulas detrás de la hoja Resumen.

Actualizar los números

• Escribe esta tabla en Sheet1!A1, incluidas las fórmulas.
• Anexa las cifras de hoy como una nueva fila del registro.
• Actualiza varios rangos en un solo lote, o borra un rango de borrador conservando su formato.

Dar forma y presentar

• Añade una hoja "Marzo", congela la fila de encabezado y ponla en negrita.
• Resalta los importes negativos en rojo con un formato condicional y añade bordes.
• Crea un gráfico de columnas de ingresos por mes en su propia hoja.
• Convierte los datos en una tabla estructurada y añade una lista desplegable con validación de datos.

Proteger y compartir

• Protege la fila de totales para que solo yo pueda editarla.
• Da a un colega acceso de edición y a todos los demás acceso de solo lectura.
• Muestra quién tiene acceso actualmente al archivo.

Cómo cambia una hoja de cálculo

1. Las herramientas de valores abordan celdas en notación A1 ('Sheet name'!A1:C10); las herramientas estructurales (hojas, formato, reglas, tablas, gráficos) abordan un sheetId numérico con índices basados en 0. get_spreadsheet proporciona los ids — los títulos de hoja no son direcciones.
2. Una escritura sobrescribe su rango; append_values añade filas después de la última fila de datos; una celda null se omite, no se borra.
3. clear_values vacía valores y fórmulas pero conserva formato, validación de datos, notas y celdas combinadas. No hay deshacer a través de la API — eliminar una hoja, filas o columnas destruye sus datos.
4. Las herramientas de lote llevan varios rangos o solicitudes en una sola llamada y cuentan una vez contra la cuota; un batchUpdate es atómico — todas sus solicitudes se aplican o ninguna.

Algunas funciones de hojas de cálculo no tienen una herramienta dedicada: celdas combinadas, rangos con nombre, bandas, filtros, segmentadores, buscar y reemplazar y reglas de formato condicional con degradado pasan por raw_request, que está limitado al origen de la API de Sheets. Una hoja de cálculo nueva aterriza en la raíz de Mi Drive — moverla a una carpeta no está cubierto, y manage_permissions no puede transferir la propiedad.

Qué puede cambiar

El cliente de IA controla los avisos de confirmación. El servidor marca las herramientas de lectura, escritura y destructivas para que el cliente pueda distinguir una inspección de un cambio en vivo.

Obtener acceso

Google Sheets requiere OAuth 2.0; una clave de API no es suficiente. Hay dos formas de entrar, y la primera no necesita archivos de configuración.

Conectar desde el chat (recomendado)

Di "conectar Google Sheets" y el asistente ejecuta el flujo contigo:

1. setup_instructions imprime la lista de verificación: crea o selecciona un proyecto de Google Cloud, habilita la API de Google Sheets, configura la pantalla de consentimiento y crea un cliente OAuth de Aplicación de escritorio.
2. Descarga el JSON de ese cliente ("Descargar JSON") y da al asistente su ruta — set_client lo almacena solo para el propietario. El secreto nunca pasa por la conversación.
3. start_login devuelve un enlace de consentimiento de Google. Ábrelo en esta máquina y aprueba; el código vuelve a un listener de una sola vez en 127.0.0.1 (PKCE), nunca a través del chat.
4. finish_login intercambia el código y guarda los tokens en ~/.config/mcp-google-sheets/credentials.json (modo 0600).

Los tokens se releen en cada llamada, por lo que la conexión funciona de inmediato — sin reiniciar la aplicación de IA. auth_status muestra qué está conectado, logout revoca y elimina.

Variables de entorno (CI, instalaciones desatendidas)

1. Crea o selecciona un proyecto de Google Cloud y habilita la API de Google Sheets. También habilita la API de Google Drive si quieres búsqueda y uso compartido de hojas de cálculo.

2. Configura la pantalla de consentimiento de OAuth y crea un cliente OAuth de Aplicación de escritorio.

3. Autoriza la cuenta de Google que posee o puede editar las hojas de cálculo. El OAuth 2.0 Playground puede obtener el token de actualización cuando Usar tus propias credenciales OAuth está habilitado.

4. Solicita el ámbito mínimo:

   https://www.googleapis.com/auth/spreadsheets
   

   Cubre todas las herramientas de Sheets. Solo search_spreadsheets y manage_permissions necesitan un ámbito de Drive adicional: https://www.googleapis.com/auth/drive, o drive.readonly solo para búsqueda, o drive.file para archivos creados a través de esta aplicación.

Los tokens de actualización de OAuth en modo de prueba pueden caducar después de siete días. Publica la aplicación OAuth, o usa una aplicación Interna en un dominio de Workspace, cuando necesites acceso de larga duración. Trata el secreto del cliente y el token de actualización como contraseñas.

Configuración

Cada variable es opcional — sin ninguna de ellas el servidor se conecta desde el chat.

* Proporciona el trío OAuth o un token de acceso. Sin credenciales, el servidor aún se inicia y lista sus herramientas; la primera llamada nombra las variables a configurar.

Datos, límites y trabajo en segundo plano

• Las solicitudes van a Google. El servidor local actualiza los tokens OAuth de Google y llama a la API de Sheets — y, solo para búsqueda y uso compartido de hojas de cálculo, a la API de Drive. Su telemetría anónima contiene un ID de instalación, versión del paquete, cliente de IA y versiones de plataforma, y nombres de herramientas — nunca tokens OAuth, datos de hojas de cálculo, argumentos de herramientas o indicaciones. Establece ASKADS_TELEMETRY=0 para optar por no participar.
• Google aplica cuotas por minuto. Los límites documentados son 300 lecturas y 300 escrituras por minuto por proyecto, y 60 de cada una por usuario; una llamada por lotes cuenta una vez, sin importar cuántos rangos o solicitudes contenga. Una hoja de cálculo tiene como máximo 10,000,000 de celdas. En 429, el servidor usa retroceso; las lecturas también se reintentan después de errores de red y 5xx, mientras que las escrituras no se reproducen después de una falla incierta.
• No hay sondeo en segundo plano. El servidor solo se ejecuta cuando se le llama. Si tu aplicación de IA admite tareas programadas, puede verificar una hoja de cálculo periódicamente.

Documentación técnica

• Catálogo de capacidades de MCP — páginas orientadas a tareas para cada herramienta.
• Todas las herramientas y entradas
• Documentación de desarrollo
• Documentación de publicación
• Referencia de la API de Google Sheets

Soporte

¿Encontraste un error o necesitas un escenario? Crea un problema o escribe en Telegram.

¡Llegaste al final!