GAS MCP

AI 어시스턴트가 Google Apps Script 프로젝트를 직접 읽고 쓰게 해주세요

코드 한 줄 바꾸고, 버전 만들기, 재배포하기, 어제 트리거가 왜 실패했을까 확인하기 — 말로 하면 됩니다.

📖 전체 설치 가이드(비엔지니어용) ・ 🔧 문제 해결

뭐가 좋을까요?

Cloudflare Workers에 배포되는 원격 MCP 서버입니다. 직접 배포하고 자신의 Google 계정으로 인가(授權)한 뒤, 데이터는 Google 계정과 서버 사이에서만 흐들고, 어떤 제3자를 거치지 않습니다.

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

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

무슨 일을 하나요?

모든 시간은 **타이베이 시간(UTC+8)**으로 표시됩니다.

먼저 알아야 할 세 가지

첫째, 컨테이너 바인딩 스크립프트는 목록에는 나타나지 않지만, 조작할 수는 있습니다. 스프레드시트/문서/폼/프레젠테이션에 바인딩된 스크립트(즉, 확장 프로그램 → Apps Script에서 연 것)는 Google 드라이브를 통해 나열될 수 없습니다 — A는 Google의 플랫폼 제한이지, 이 프로젝트의 문제가 아닙니다. 대부분 이런 유형의 스크립트라면 list_projects는 빈 값을 반환합니다.

해결 방법은 scriptId를 직접 주면 되고, 나머지 14개 도구는 모두 그대로 사용할 수 있습니다.

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

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

AI에게 "scriptId 1Ge-MUVs... 이 스크립트의 Code.gs를 확인해 줘"라고 말하면 바로 시작할 수 있습니다.

둘째, 이 프로젝트는 Google 드라이브의 읽기 전용 권한을 지닙니다. Apps Script API는 "내 모든 스크립트 프로젝트 나열하기" 기능을 제공하지 않습니다 (공식 이슈]). 유일한 방법은 Google 드라이브에서 파일 형식으로 조회하는 것입니다. 그래서 이 프로젝트는 drive.metadata.readonly를 추가했습니다 — 이 용도를 위한 최소 권한입니다: 읽는 것은 파일 이름과 ID뿐, 어떤 파일 내용도 없지 못하며, Google Drive 파일을 만들거나 수정하거나 삭제할 수 없습니다.

셋째, 쓰기는 전체를 덮어쓰므로 반드시 백업을 만듭니다. Apps Script API의 updateContent는 보낸 파일 목록으로 전 subtitle을 대체합니다 — 목록에 없는 파일은 그대로 사라집니다. 그러므로 write_file은 "전체 목록을 먼저 읽고 → 버전 복원 지점 만들기 → 병합 → 전체 재전송" 순서로 진행하며, 백업에 실패하면 쓰기를 중단합니다: 다시는 안 쓰는 한이 있어도 대비가 없는 상황에서 덮어쓰지 않습니다. 모든 쓰기에 대한 응답에는 복원 지점이 몇 번 버전인지 표시됩니다.

run_function에 대해서(기본 비활성)

GAS 함수의 원격 실행은 다른 기능보다 진입 장벽이 높고, AI가 코드를 직접 실행하게 되는 것이므로 기본적으로 등록하지 않습니다. 실행하려면 /setup에서 체크하고 다음 세 가지 조건이 모두 충족되어야 합니다 — 하나라도 없다면 403이 반환됩니다:

1. 스크립트 편집기에서 "배포 → 새 배포로 → API 엔드포인트"를 선택해야 합니다.

2. 스크립트의 Google Cloud 프로젝트는 이 서버에서 사용하는 것과 동일해야 합니다.

3. 승인된 토큰이 스크립트 appsscript.json의 모든 권한(scopes)을 포함해야 합니다 — 자동으로 추론이 불가능하므로 /setup에서 (직접) 확인을 수 있어야 합니다.

지원되는 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의 **민감한 권한(sensitive scope)**에 해당합니다. 이를 공개 공용 서비스로 만들려면 개발자가 Google OAuth 인증과 CASA 연간 보안 평가를 받아야 하며, 비용이 높고, 모든 사람?의 프그램이 모두 같은 서버를 거쳐야 합니다.

각자 직접 구축화면, 어떤 검토도 굳이와 없고, 데이터는 자신이 직접 보관하며, 100명 상한이라는 제한도 없습니다. 겨우 20분 정도 설정을 한 번 해두면 이후에는 신경 쓸 일이 없습니다.

보안 설계

• 자격 증명의 암호 저장: Google의 refresh token은 @cloudflare/workers-oauth-provider 기반으로 암호화되어 사용자 자신의 Cloudflare KV에 저장되며, 어떤 제3자도 전달되지 않습니다.

• 소유자 고정: 최초로 인증된 Google 계정을 소유자로 잠그고, 다른 사람이 서버 주소를 알아도 접근할 수 없습니다.

• 쓰기 전 백업 의무: 모든 write_file / delete_file 작업에서 자동으로 버전을 만들고, 백업 실패 시 중단됩니다.

• 실행은 명시적으로 안: run_function은 기본적으로 등록되지 않으므로, tools/list 목록에 표시되지 않습니다.

• 최소 권한: 실제로 필요한 scope만 요청하며, 드라이브는 읽기 전용 메타데이터(metadata)만 사용합니다.

• 로그 없음: 코드를 실시간으로 가져와 즉시 사용하고 기록하지 않으며, 어떤 데이터베이스나 로그 파일에도 저장하지 않습니다.

전체적인 정보는 서비스가 배포된 뒤 <your-url>/privacy 에 나와 있습니다.

개발자를 위한

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

기술 세부 사항

• 통신 계층: Streamable HTTP, 종점 /mcp

• 프로토콜 버전: 2025-era(initialize handshake)와 2026-07-28(stateless) 클라이언트를 모두 지원하며, @modelcontextprotocol/server v2의 레거시 리그렉 배크로 자동 처리됩니다.

• 인증: 일 하나의 Worker가 MCP 클라이언트에 대한 OAuth 2.1 서버이자, Google 클라이언트(OAuth client) 역할을 합니다. 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