GAS MCP

Permite que tu asistente de IA lea y escriba directamente en tus proyectos de Google Apps Script

Cambia una línea de código, crea una versión, vuelve a implementar, averigua por qué falló el activador de ayer: solo tienes que decirlo.

📖 Guía de instalación completa (para no programadores) ・ 🔧 Solución de problemas

Qué es esto

Un servidor MCP remoto desplegado en Cloudflare Workers. Tú mismo despliegas tu propia instancia y la autorizas con tu propia cuenta de Google. Los datos solo circulan entre tu cuenta de Google y tu Worker, sin pasar por ningún tercero.

你：「出缺席統計那支腳本，昨天的每日觸發器為什麼失敗？」

AI：共 12 筆執行紀錄，其中 3 筆失敗：
    - dailyReport｜TIME_DRIVEN｜FAILED｜2026-08-20 07:00，耗時 4.2s
    ...
    我看了 Code.gs 第 17 行，getRange 的列數是從空白試算表算出來的，
    所以在資料還沒進來時會是 0。要我改成先檢查 lastRow 嗎？

Qué puede hacer

Las horas se muestran siempre en hora de Taipéi (UTC+8).

Tres cosas que debes saber primero

Uno: los scripts vinculados a contenedores no aparecen en la lista, pero se pueden operar sin problema. Los scripts incrustados en hojas de cálculo, documentos, formularios o presentaciones (es decir, los que se abren desde «Extensiones → Apps Script») no se pueden enumerar a través de Google Drive: es una limitación de la plataforma de Google, no un defecto de este proyecto. Si la mayoría de tus scripts son de este tipo, list_projects devolverá una lista vacía.

La solución es proporcionar directamente el scriptId; los otros 14 herramientas funcionan con total normalidad:

到 https://script.google.com/home/all 點開專案，
網址 .../projects/<這一長串>/edit 就是 scriptId

或：容器檔案 → 擴充功能 → Apps Script → 專案設定 → 複製指令碼 ID

Dile a la IA «ayúdame a ver el Code.gs del script con scriptId 1Ge-MUVs...» y podrás empezar directamente.

Dos: este proyecto tiene permiso de solo lectura sobre Google Drive. La API de Apps Script no ofrece un método para «listar todos mis proyectos de scripts» (issue oficial); la única vía es consultar Drive por tipo de archivo. Por eso este proyecto solicita drive.metadata.readonly, que es el alcance mínimo para lograrlo: solo puede leer nombres de archivos e IDs; no puede leer ningún contenido de archivos, ni crear, modificar o eliminar ningún archivo de Drive.

Tres: la escritura sobrescribe el paquete completo, así que siempre se crea una copia de seguridad primero. El método updateContent de la API de Apps Script sustituye todo el proyecto por la lista de archivos que envíes: los archivos que no se incluyan desaparecen directamente. Por eso write_file sigue el flujo de «leer primero la lista completa → crear un punto de restauración de versión → fusionar → enviar el paquete completo», y si la copia de seguridad falla, se aborta la escritura: mejor no escribir que sobrescribir sin red de seguridad. Cada respuesta de escritura te indicará cuál es el número de versión del punto de restauración.

Sobre run_function (desactivada por defecto)

Ejecutar funciones de GAS de forma remota tiene requisitos más altos que cualquier otra función, y equivale a dejar que la IA ejecute código directamente, por lo que no está registrada por defecto. Para activarla, márcala en /setup y cumple tres condiciones: si falta una sola, obtendrás un 403.

1. El script debe implementarse en el editor mediante «Implementar → Nueva implementación → Ejecutable de API».

2. El proyecto de Google Cloud del script debe ser el mismo que utiliza este servidor.

3. El token autorizado debe cubrir cada uno de los scopes declarados en appsscript.json del script: esto no se puede deducir automáticamente; debes pegarlo línea por línea en /setup.

Qué asistentes de IA son compatibles

Es un servidor MCP estándar (Streamable HTTP + OAuth 2.1), no está ligado a ningún proveedor en particular:

Instalación

Haz clic en el botón «Deploy to Cloudflare» de arriba y sigue la guía de instalación completa, unos 20 minutos.

1. 點部署按鈕                → 得到你的專屬網址
2. 開啟 Apps Script API 存取  → 一個開關，但最常被忘記
3. 在 Google Cloud 開權限     → 步驟最多的一段
4. 打開 <你的網址>/setup      → 貼上憑證、設管理密碼
5. 把 <你的網址>/mcp 貼進 AI 助理 → 完成

¿Por qué desplegarlo uno mismo y no compartir una instancia común?

El contenido de los proyectos de scripts pertenece al ámbito de permisos sensibles de Google. Para convertirlo en un servicio público compartido, el desarrollador debe superar la revisión de OAuth de Google y la evaluación de seguridad CASA: un coste elevado, y además el código de todos pasaría por el mismo servidor de un tercero.

Si cada uno despliega su propia instancia: no se necesita ninguna revisión, los datos quedan solo en tus manos y no existe el límite de 100 usuarios. El coste es dedicar unos 20 minutos a la configuración inicial; después ya no hay que tocarlo.

Diseño de seguridad

• Credenciales cifradas en almacenamiento: el refresh token de Google se cifra mediante @cloudflare/workers-oauth-provider y se guarda en tu propio Cloudflare KV; no se envía a ningún tercero

• Bloqueo de propietario: la primera cuenta de Google que complete la autorización queda vinculada; los demás, aunque conozcan la URL, no podrán acceder

• Copia de seguridad obligatoria antes de escribir: cada write_file / delete_file crea automáticamente un punto de restauración de versión; si la copia falla, se aborta

• Ejecución requiere activación explícita: run_function no está registrada por defecto; ni siquiera aparece en tools/list

• Privilegios mínimos: solo se solicitan los scopes realmente necesarios; Drive solo necesita metadatos de solo lectura

• Sin dejar rastro: el código se obtiene al momento y se descarta al terminar; no se escribe en ninguna base de datos ni archivo de registro

La explicación completa está en <tu-url>/privacy tras el despliegue.

Para desarrolladores

npm install
npm test          # 87 個測試
npm run typecheck
npx wrangler dev

Detalles técnicos

• Capa de transporte: Streamable HTTP, endpoint /mcp

• Versión del protocolo: compatible tanto con clientes de la era 2025 (handshake initialize) como con los de 2026-07-28 (stateless), gestionado automáticamente por el fallback heredado de @modelcontextprotocol/server v2

• Autorización: el mismo Worker es a la vez un servidor de autorización OAuth 2.1 para los clientes MCP y un cliente OAuth para Google. Soporta DCR, PKCE S256, metadatos de recursos RFC 9728 e iss RFC 9207

Estructura del proyecto

src/
├── index.ts          OAuthProvider 組裝（Worker 進入點）
├── auth-handler.ts   /authorize、Google callback、首頁與法律頁路由
├── setup-page.ts     /setup 設定精靈（含遠端執行開關）
├── legal-pages.ts    隱私權政策與服務條款
├── config.ts         設定儲存與管理密碼
├── state.ts          HMAC 簽章的 OAuth state
├── errors.ts         Google API 錯誤 → 可行動的中文訊息
├── google/
│   ├── oauth.ts      Google OAuth 與動態 scope 組合
│   ├── apps-script.ts  script.googleapis.com REST client
│   └── drive.ts      Drive API（只用來列出腳本專案）
└── mcp/
    ├── handler.ts    MCP handler 與每請求的 server 工廠
    ├── tools-read.ts 唯讀工具
    ├── tools-write.ts 寫入工具（含備份邏輯）
    ├── tools-run.ts  run_function（僅在啟用時註冊）
    ├── shared.ts     工具回傳值與錯誤包裝
    └── datetime.ts   台北時區換算

Términos de licencia

MIT