mcp-google-apps-script

Google Apps Script MCP

Inglés | Русский

A1 Google Apps Script MCP permite que una aplicación de IA escriba y opere Google Apps Script en lenguaje natural. Crea un proyecto de script, lee y edita su código, crea instantáneas de versiones, gestiona implementaciones, ejecuta funciones y lee el historial de ejecución.

Utiliza la API de Google Apps Script con tu cuenta de Google. Distingue el código HEAD editable de las versiones inmutables y hace explícitos los límites de la API de Apps Script en lugar de dar a entender que cualquier tarea de scripting es posible.

• 19 herramientas. Crea proyectos independientes y vinculados, lee y actualiza archivos de código, crea instantáneas de versiones inmutables, gestiona implementaciones, ejecuta funciones e inspecciona el historial de ejecución y las métricas.
• Se conecta desde la conversación. Di "conectar Google Apps Script": 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 versiones son inmutables. Una versión crea una instantánea de HEAD y nunca puede editarse ni eliminarse; las implementaciones apuntan a versiones, por lo que puedes publicar y revertir sin cambiar una URL.
• El manifiesto siempre sobrevive. El modo de fusión mantiene el manifiesto appsscript y todos los archivos que no mencionaste; el modo de reemplazo rechaza un conjunto de archivos sin el manifiesto antes de cualquier tráfico de red.
• Conserva tu scriptId. La API no puede listar proyectos ni eliminarlos — el scriptId devuelto por create_project es el único identificador.
• Ámbitos de Google mínimos. Cada operación nombra su propio ámbito (script.projects, script.deployments, script.processes, script.metrics); solicita solo lo que tus tareas necesiten.

Comienza con una pregunta de solo lectura:

Muéstrame los archivos de mi script de informes y qué funciones fallaron esta semana.

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

Véalo funcionar en un minuto

Tú: Muestra el código y las ejecuciones recientes de mi script de informes.

Asistente: Muestra cada archivo con su código fuente y el historial de ejecución — qué funciones se ejecutaron, cuándo y cuáles fallaron. Nada cambia.

Tú: Añade un helper formatDate al archivo Utils y mantén todo lo demás como está.

Asistente: Muestra el código propuesto y confirma que el modo de fusión deja los demás archivos intactos, luego pide confirmación antes de escribir.

Tú: Confirmo.

Asistente: Escribe el archivo en HEAD. No crea una versión, no vuelve a implementar ni ejecuta nada a menos que lo pidas por separado.

Contenido

• Inicio rápido
• Qué puedes pedirle que haga
• Cómo cambia un proyecto
• Qué puede cambiar
• Cómo 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 momento de la instalación — el servidor se conecta desde la conversación.

1. Añade el servidor a tu aplicación de IA.
2. Di "conectar Google Apps Script": 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-apps-script \
  -- npx -y mcp-google-apps-script@latest

codex mcp list

claude mcp add \
  --transport stdio --scope user google-apps-script \
  -- npx -y mcp-google-apps-script@latest

claude mcp list

{
  "mcpServers": {
    "google-apps-script": {
      "command": "npx",
      "args": ["-y", "mcp-google-apps-script@latest"]
    }
  }
}

{
  "mcpServers": {
    "google-apps-script": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-apps-script@latest"]
    }
  }
}

{
  "servers": {
    "google-apps-script": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-apps-script@latest"]
    }
  }
}

Qué puedes pedirle que haga

Inspeccionar un proyecto y sus ejecuciones

• Muestra los archivos de este script y explica qué hace cada función.
• ¿Qué funciones fallaron esta semana? Muestra el historial de ejecución de sendDigest.
• ¿Cuántos usuarios, ejecuciones y fallos tuvo este script en los últimos 7 días?

Escribir y evolucionar código

• Crea un proyecto independiente, o un script vinculado a un Doc, Sheet, Slides o Form.
• Añade una función auxiliar a un archivo sin tocar los demás.
• Crea una instantánea del código actual como versión con una descripción antes de refactorizar.

Publicar, ejecutar y revertir

• Implementa la versión 4 y muestra sus puntos de entrada — URL de aplicación web o configuración ejecutable por API.
• Ejecuta sendDigest y muestra el resultado; si el script lanza una excepción, muestra el seguimiento de la pila.
• Reapunta la implementación de vuelta a la versión 3 sin cambiar su URL.

Cómo cambia un proyecto

1. create_project crea un proyecto — independiente, o vinculado a un Doc, Sheet, Slides o Form. Conserva el scriptId devuelto: la API no puede listar proyectos.
2. El código vive en HEAD como archivos identificados por nombre sin extensión. update_project_content fusiona por defecto — inserta o actualiza los archivos que nombres y conserva el resto — y solo reemplaza el conjunto completo cuando se le pide; el manifiesto appsscript nunca puede eliminarse.
3. create_version crea una instantánea de HEAD como versión inmutable — sin edición, sin eliminación, los números solo crecen.
4. Una implementación expone una versión como aplicación web o ejecutable por API. Actualizar una implementación la reapunta a otra versión sin cambiar su URL; la implementación automática @HEAD no puede eliminarse.

La API tampoco puede eliminar un proyecto — eso significa eliminar su archivo de Drive, lo cual este servidor no cubre. run_function requiere una implementación ejecutable por API, un cliente OAuth del mismo proyecto de Cloud que el script y los ámbitos propios del script en el token; Apps Script detiene cualquier ejecución después de 6 minutos. El historial de ejecución muestra estado y tiempos pero no mensajes de error — esos viven en Cloud Logging o provienen de volver a ejecutar la función.

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.

Cómo obtener acceso

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

Conectar desde el chat (recomendado)

Di "conectar Google Apps Script" y el asistente ejecutará el flujo contigo:

1. setup_instructions imprime la lista de verificación: crea o selecciona un proyecto de Google Cloud, habilita Apps Script API, 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 dale al asistente su ruta — set_client lo almacena con permisos 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 un solo uso 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-apps-script/credentials.json (modo 0600) y los verifica con una llamada real a la API de Apps Script — así, una API que sigue desactivada se detecta en ese momento.

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 Google Apps Script API.

2. Activa el interruptor por cuenta en script.google.com/home/usersettings — sin él, cada llamada falla con 403.

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

4. Autoriza la cuenta de Google que posee los scripts. El Playground de OAuth 2.0 puede obtener el token de actualización cuando Usar tus propias credenciales OAuth está habilitado.

5. Solicita los ámbitos para las herramientas que planeas usar:

   https://www.googleapis.com/auth/script.projects
   https://www.googleapis.com/auth/script.deployments
   https://www.googleapis.com/auth/script.processes
   https://www.googleapis.com/auth/script.metrics
   

   Para uso solo de inspección, reemplaza los dos primeros con las variantes de solo lectura script.projects.readonly y script.deployments.readonly; list_processes y get_project_metrics aún necesitan script.processes y script.metrics, que no tienen forma más restringida. run_function no necesita ninguno de estos ámbitos — en su lugar, el token debe llevar todos los ámbitos que el propio script de destino usa, y el cliente OAuth debe pertenecer al mismo proyecto de Cloud que el script.

Los tokens de actualización de OAuth en modo de prueba pueden expirar 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.

La herramienta setup_instructions devuelve esta misma lista de verificación y funciona incluso antes de que se configuren las credenciales.

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.

Datos, límites y trabajo en segundo plano

• Las solicitudes van a Google Apps Script. El servidor local actualiza los tokens de OAuth de Google y llama a la API de Apps Script. 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 de OAuth, fuentes de scripts, argumentos de herramientas o mensajes. Establece ASKADS_TELEMETRY=0 para optar por no participar.
• Las escrituras nunca se reproducen a ciegas. 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 — un create_version duplicado acumula versiones inmutables, y un run_function duplicado ejecuta efectos secundarios dos veces. Después de una falla ambigua, verifica list_versions o el historial de ejecución en lugar de reenviar.
• No hay sondeo en segundo plano. El servidor solo se ejecuta cuando se le llama, y una función solo se ejecuta cuando la solicitas. Los scripts mantienen sus propios activadores de Apps Script en el lado de Google; si tu aplicación de IA admite tareas programadas, también puede verificar el historial de ejecución 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 Apps Script

Soporte

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

¡Llegaste al final!