apps-script-mcp-server

Claude가 Google Apps Script(.gs, .html, appsscript.json) 코드를 스크립트 프로젝트에 직접 읽고 푸시할 수 있게 해주는 MCP 서버입니다. 더 이상 Apps Script 편집기에 코드를 수동으로 복사하여 붙여넣을 필요가 없습니다.

Kwara 질병 감시 시스템(KWARAB 대시보드)용으로 제작되었지만, 편집 권한이 있는 모든 Apps Script 프로젝트에서 작동합니다.

할 수 있는 작업

미리 알아두어야 할 중요한 제한 사항: apps_script_update_file / apps_script_update_content로 코드를 푸시하면 스크립트 편집기에 입력하고 저장하는 것과 동일하게 편집 가능한 프로젝트가 업데이트됩니다. 이미 배포된 항목(예: 라이브 웹 앱 URL 또는 특정 배포 버전에 연결된 트리거)은 자동으로 업데이트되지 않습니다. 변경 사항을 라이브로 적용하려면 버전을 생성하고(apps_script_create_version) Apps Script 편집기에서 다시 배포하십시오. 이 서버는 의도적으로 배포 게시를 다루지 않습니다. 이는 더 중요한 작업이므로 처음 몇 번은 수동으로 수행하는 것이 좋습니다.

1. 일회성 Google Cloud 설정 (먼저 수행)

Apps Script API가 활성화되고 OAuth 클라이언트가 있는 Google Cloud 프로젝트가 필요합니다. 약 5분 정도 소요됩니다.

1. Google Cloud 프로젝트 생성 또는 선택 https://console.cloud.google.com/projectcreate로 이동하여 프로젝트를 생성합니다(이름은 무엇이든 상관없음 — 예: "kwarab-apps-script-mcp"). 이미 다른 Kwara/Ekiti 작업에 사용 중인 GCP 프로젝트가 있다면 재사용할 수 있습니다.

2. 프로젝트에서 Apps Script API 활성화 https://console.cloud.google.com/apis/library/script.googleapis.com로 이동하여 프로젝트를 선택하고 Enable을 클릭합니다.

3. OAuth 동의 화면 구성 https://console.cloud.google.com/apis/credentials/consent로 이동합니다.

   • 사용자 유형: External(Google Workspace 조직이 있는 경우 Internal도 가능)

   • 앱 이름(예: "Apps Script MCP") 입력, 지원 연락처로 이메일 입력

   • 범위: 여기서 범위를 추가하지 않아도 됩니다. 서버가 직접 요청합니다.

   • 테스트 사용자: 자신의 Google 계정 이메일을 추가합니다(앱이 "Testing" 상태인 동안 필요하며, 개인/내부용으로는 괜찮습니다).

4. OAuth 클라이언트 생성 https://console.cloud.google.com/apis/credentials로 이동합니다.

   • Create Credentials → OAuth client ID 클릭

   • 애플리케이션 유형: Desktop app

   • 이름을 지정합니다(예: "Apps Script MCP Desktop")

   • Create 클릭 후 Download JSON 클릭

5. 다운로드한 파일을 이 프로젝트의 루트 폴더(이 README와 같은 폴더)에 credentials.json으로 저장합니다. 이 파일을 커밋하거나 공유하지 마십시오. 이 파일은 OAuth 클라이언트를 식별합니다(개인 계정은 아니지만 여전히 비공개로 유지해야 함).

6. 자신의 Google 계정에 대해 Apps Script API 활성화 이는 2단계와 별개입니다(2단계는 프로젝트에 대해 API를 활성화하는 것이고, 이 단계는 스크립트를 소유/편집하는 Google 계정에 대해 활성화하는 것입니다). https://script.google.com/home/usersettings로 이동하여 **"Google Apps Script API"**를 켭니다.

2. 설치 및 인증

npm install
npm run build
npm run authorize

npm run authorize는 브라우저를 열고, Kwara 질병 감시 Apps Script 프로젝트에 액세스할 수 있는 Google 계정으로 로그인하도록 요청하며, 액세스 승인을 요청합니다. 승인 후 이 폴더에 token.json에 새로 고침 토큰을 저장합니다. 이 작업은 한 번만 수행하면 됩니다(액세스를 취소하거나 Google 계정을 전환하는 경우 다시 실행).

브라우저가 자동으로 열리지 않는 경우: 터미널에 URL이 출력됩니다. URL을 복사하여 브라우저에 붙여넣고 승인하면 스크립트가 수신 대기 중인 localhost로 리디렉션됩니다. 터미널에서 성공을 확인합니다.

3. Claude에 연결

옵션 A: 로컬 (stdio) — Claude Code / Claude Desktop

MCP 구성(예: claude_desktop_config.json 또는 Claude Code MCP 설정)에 추가:

{
  "mcpServers": {
    "apps-script": {
      "command": "node",
      "args": ["/absolute/path/to/apps-script-mcp-server/dist/index.js"]
    }
  }
}

이 구성을 추가한 후 Claude Desktop / Claude Code를 다시 시작합니다. apps-script가 연결된 MCP 서버 중에 표시되고 apps_script_update_file과 같은 도구를 사용할 수 있습니다.

옵션 B: 원격 (HTTP), 예: Render에 호스팅

서버는 독립형 HTTP 서비스로도 실행됩니다. TRANSPORT=http로 설정합니다. 이 리포지토리의 render.yaml이 자동으로 구성하는 방식입니다. 아래 Deploying to Render를 참조하십시오.

원격 서버는 URL을 가진 모든 사람이 접근할 수 있으므로 /mcp에 대한 모든 요청에는 설정한 MCP_SERVER_TOKEN 환경 변수와 일치하는 Bearer 토큰이 포함되어야 합니다:

Authorization: Bearer <your MCP_SERVER_TOKEN value>

Claude의 원격 MCP 커넥터 설정에서 서버 URL(https://<your-service>.onrender.com/mcp)을 추가하고 해당 헤더를 설정합니다. /healthz는 의도적으로 인증되지 않았으므로 Render의 상태 확인이 접근할 수 있습니다.

Render에 배포

이 리포지토리에는 render.yaml Blueprint가 포함되어 있어 Render가 대부분의 설정이 미리 채워진 서비스를 생성할 수 있습니다.

1. Render 대시보드에서: New → Blueprint, GitHub 계정을 아직 연결하지 않았다면 연결하고 이 리포지토리를 선택합니다. Render가 render.yaml을 읽습니다.

2. Render가 sync: false로 표시된 환경 변수를 입력하도록 요청합니다:

   • MCP_SERVER_TOKEN — 긴 임의의 문자열을 만듭니다(예: openssl rand -hex 32). Claude가 Bearer 토큰으로 보내야 하는 값입니다.

   • GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET, GOOGLE_OAUTH_REFRESH_TOKEN — 로컬에서 먼저 생성(위 1~2단계, npm run authorize 포함)한 다음 결과 token.json을 열고 client_id, client_secret, refresh_token을 Render의 환경 변수 필드에 복사합니다. Render는 브라우저를 얻지 못하므로 이 헤드리스 자격 증명 경로가 로컬 npm run authorize 단계를 대체합니다.

3. 배포합니다. 라이브가 되면 MCP 엔드포인트는 https://<your-service>.onrender.com/mcp입니다.

4. 무료 플랜에서는 비활성 후 Render가 서비스를 종료합니다. 유휴 후 첫 번째 요청은 다시 시작하는 동안 느려집니다(콜드 스타트).

4. 사용 방법

Kwara 질병 감시 Apps Script 프로젝트의 스크립트 ID가 필요합니다. https://script.google.com에서 프로젝트를 열고 URL에서 ID를 복사하여 찾으십시오:

https://script.google.com/home/projects/<THIS_IS_THE_SCRIPT_ID>/edit

(Apps Script가 KWARAB Google 스프레드시트에 바인딩된 경우 독립형이 아니라면 스프레드시트를 열고 Extensions → Apps Script로 이동하여 동일한 편집기와 URL로 이동합니다.)

그런 다음 이 MCP 서버가 연결된 Claude 대화에서 다음과 같이 말할 수 있습니다:

• "스크립트 <scriptId>의 현재 Code.gs를 보여줘"

• "Code.gs의 sendAlertEmail 함수를 업데이트하여 DSNO 감독자도 참조로 추가해"

• "이 새로운 Utils.gs 파일을 다음 도우미 함수와 함께 푸시해: ..."

• "'Add AFP EPID auto-compose logic'라는 새 버전을 만들어"

보안 참고 사항

• credentials.json과 token.json은 모두 편집 가능한 Apps Script 프로젝트에 대한 액세스 권한을 부여합니다. 버전 관리에서 제외하고 공유하지 마십시오(.gitignore 포함됨).

• 요청된 OAuth 범위(script.projects, script.deployments)에는 스크립트 프로젝트 콘텐츠를 읽고/쓰고 배포를 검사하는 데 필요한 것 이상의 Gmail, Sheets 또는 Drive 액세스가 포함되지 않습니다.

• 언제든지 액세스를 취소하려면: https://myaccount.google.com/permissions → 위 4단계에서 설정한 OAuth 클라이언트 이름 찾기 → Remove Access. 그 후 token.json을 삭제하십시오.

문제 해결