GAS MCP

AIアシスタントがあなたのGoogle Apps Scriptプロジェクトを直接読み書きできるようにする

コードを1行変更する、バージョンを作る、再デプロイする、昨日のトリガーがなぜ失敗したのか調べる——話すだけでOK。

📖 完全インストールガイド（非エンジニア向け） ・ 🔧 トラブルシューティング

これは何か

Cloudflare Workers上にデプロイするリモートMCPサーバーです。自分でデプロイし、自分のGoogleアカウントで認証するため、データはあなたのGoogleアカウントとあなたのWorkerの間だけで流れ、第三者を経由しません。

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

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

できること

時刻はすべて**台北時間（UTC+8）**で表示されます。

事前に知っておくべき3つのこと

1. コンテナバインドスクリプトは一覧に出ませんが、操作は完全に可能です。 スプレッドシート／ドキュメント／フォーム／スライドにバインドされたスクリプト（つまり「拡張機能 → Apps Script」から開くタイプ）は、Googleドライブ経由では列挙できません——これはGoogleのプラットフォーム制限であり、本プロジェクトの欠陥ではありません。 あなたのスクリプトがほとんどこのタイプの場合、list_projects は空を返します。

解決策はscriptIdを直接指定することです。残りの14個のツールはすべて通常どおり動作します：

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

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

AIに「scriptId 1Ge-MUVs... のスクリプトの Code.gs を見て」と伝えるだけで、すぐに始められます。

2. 本プロジェクトはGoogleドライブの読み取り専用権限を持っています。 Apps Script APIには「自分のすべてのスクリプトプロジェクトを一覧表示する」メソッドはありません （公式issue）。 唯一の方法は、ドライブ経由でファイルタイプで検索することです。そのため、本プロジェクトは drive.metadata.readonly を申請しています——これはこの目的を達成するための最小範囲です： ファイル名とIDのみ読み取れ、ファイルの内容は一切読み取れません。また、ドライブファイルの作成・変更・削除もできません。

3. 書き込みは全体を上書きするため、必ず先にバックアップします。 Apps Script APIの updateContent は、送信したファイルリストでプロジェクト全体を置き換えます——含まれていないファイルは消えてしまいます。 そのため write_file は「完全なリストを読み取り → バージョン復元ポイントを作成 → マージ → 全体を送り返す」という流れを採用しており、 バックアップに失敗したら書き込みを中止します：書かないほうが、逃げ道がない状態で上書きするよりましです。 書き込みのたびに、復元ポイントが何番目のバージョンかを返信で知らせます。

run_function について（デフォルトでは無効）

GAS関数のリモート実行は他の機能よりハードルが高く、AIに直接コードを実行させることになるため、デフォルトでは登録されていません。 有効にするには、/setup でチェックし、次の3つの条件を満たす必要があります——1つでも欠けると403になります：

1. スクリプトはエディタで「デプロイ → 新しいデプロイ → API実行可能」を選択している必要があります。

2. スクリプトのGoogle Cloudプロジェクトは、本サーバーが使用しているものと同じである必要があります。

3. 認証トークンは、スクリプトの appsscript.json で宣言されているすべてのスコープをカバーしている必要があります—— これは自動では推測できないため、/setup で1行ずつ貼り付ける必要があります。

対応しているAIアシスタント

これは標準のMCPサーバー（Streamable HTTP + OAuth 2.1）であり、特定のベンダーに縛られません：

インストール

上部の「Deploy to Cloudflare」ボタンをクリックし、完全インストールガイド に従ってください。約20分かかります。

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

なぜ自分でデプロイするのか。共有サーバーではダメなのか？

スクリプトプロジェクトの内容はGoogleの機密権限スコープに該当します。公開の共有サービスにするには、開発者はGoogleのOAuth審査と CASA年間セキュリティ評価を通過する必要があります——コストが高く、全員のコードが同じ他人のサーバーを経由することになります。

各自で構築する方式に変更：審査は不要、データは自分の手元にのみ残り、100人という上限もありません。 代わりに約20分の初期設定が必要ですが、その後は触る必要がありません。

セキュリティ設計

• 認証情報を暗号化して保存：Googleのrefresh tokenは @cloudflare/workers-oauth-provider によって暗号化され、あなた自身のCloudflare KVに保存されます。第三者に送信されることはありません

• オーナー固定：最初に認証を完了したGoogleアカウントが固定され、他の人はURLを知っていてもアクセスできません

• 書き込み前のバックアップ必須：write_file / delete_file のたびに自動でバージョン復元ポイントを作成し、バックアップ失敗時は中止します

• 実行には明示的な有効化が必要：run_function はデフォルトでは登録されず、tools/list にも表示されません

• 最小権限：実際に必要なスコープのみを申請し、Driveは読み取り専用のメタデータのみ

• 痕跡を残さない：コードは即時取得し、使用後は破棄。データベースやログファイルには一切書き込みません

詳細はデプロイ後の <あなたのURL>/privacy を参照してください。

開発者向け

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

技術詳細

• トランスポート層：Streamable HTTP、エンドポイント /mcp

• プロトコルバージョン：2025-era（initialize ハンドシェイク）と2026-07-28（ステートレス）の両方のクライアントをサポート。 @modelcontextprotocol/server v2のレガシーフォールバックが自動で処理します

• 認証：同じWorkerがMCPクライアントに対するOAuth 2.1認可サーバーであり、Googleに対するOAuthクライアントでもあります。DCR、PKCE S256、RFC 9728リソースメタデータ、RFC 9207 iss をサポート

プロジェクト構成

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

ライセンス

MIT