GAS MCP

Let AI assistants directly read and write your Google Apps Script projects

Change a line of code, create a version, redeploy, check why yesterday's trigger failed—just say it.

📖 Full installation guide (for non-engineers) ・ 🔧 Troubleshooting

What this is

A remote MCP server deployed on Cloudflare Workers. You deploy your own instance and authorize with your own Google account—data flows only between your Google account and your Worker, never through any third party.

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

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

What it can do

Times are always displayed in**Taipei time (UTC+8)**.

Three things you need to know first

One: Container-bound scripts can't be listed, but can be fully operated. Scripts bound to spreadsheets / documents / forms / slides (i.e., the kind opened from "Extensions → Apps Script") cannot be enumerated through Google Drive—this is a Google platform limitation, not a flaw in this project. If most of your scripts are of this type, list_projects will return empty.

The solution is to provide the scriptId directly; all other 14 tools work normally:

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

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

Just tell the AI "help me look at the Code.gs of this script with scriptId 1Ge-MUVs..." and it can start right away.

Two: This project has read-only access to Google Drive. The Apps Script API doesn't provide a way to "list all my script projects" (official issue), the only path is querying Drive by file type. So this project requests drive.metadata.readonly—this is the minimal scope to achieve that goal: it can only read file names and IDs, not any file content, and cannot create, modify, or delete any Drive files.

Three: Writes are full-package overwrites, so a backup always comes first. The Apps Script API's updateContent replaces the entire project with the file list you send—files not included simply disappear. write_file therefore follows a "read full list first → create version restore point → merge → send full package back" flow, and if the backup fails, the write is aborted: better to not write than to overwrite with no way back. Every write response tells you which version number the restore point is.

About run_function (disabled by default)

Remotely executing GAS functions has a higher bar than other features, and it effectively lets the AI execute code directly, so it's not registered by default. To enable it, check the box in /setup and satisfy three conditions—missing any one gets you a 403:

1. The script must have "Deploy → New deployment → Executable API" in the editor.

2. The script's Google Cloud project must be the same one this server uses.

3. The authorized token must cover every scope declared in the script's appsscript.json— this can't be inferred automatically; you need to paste them line by line in /setup.

Which AI assistants are supported

This is a standard MCP server (Streamable HTTP + OAuth 2.1), not tied to any specific vendor:

Installation

Click the "Deploy to Cloudflare" button above, then follow the full installation guide, about 20 minutes.

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

Why deploy your own instead of sharing one for everyone?

Script project content falls under Google's sensitive permission scope. To make it a public shared service, the developer must pass Google's OAuth review and CASA annual security assessment—costly, and everyone's code would pass through someone else's server.

Deploying your own instead: no review needed, data stays in your own hands, and no 100-user cap. The cost is about 20 minutes of one-time setup, and you never touch it again.

Security design

• Encrypted credential storage: Google refresh tokens are encrypted by @cloudflare/workers-oauth-provider and stored in your own Cloudflare KV, never sent to any third party

• Owner lock: The first Google account to complete authorization is bound; others can't access it even if they know the URL

• Backup before every write: Each write_file / delete_file automatically creates a version restore point; the write aborts if the backup fails

• Execution requires explicit opt-in: run_function isn't registered by default, so it's not even visible in tools/list

• Least privilege: Only requests the scopes actually needed; Drive only needs read-only metadata

• No traces left: Code is fetched on demand and discarded immediately, never written to any database or log

Full details are at <your-url>/privacy after deployment.

For developers

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

Technical details

• Transport: Streamable HTTP, endpoint /mcp

• Protocol versions: Supports both 2025-era (initialize handshake) and 2026-07-28 (stateless) clients, handled automatically by the legacy fallback in @modelcontextprotocol/server v2

• Authorization: The same Worker is both the OAuth 2.1 authorization server for MCP clients and the OAuth client for Google. Supports DCR, PKCE S256, RFC 9728 resource metadata, RFC 9207 iss

Project structure

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   台北時區換算

License

MIT