Claude Google Apps Script MCP Guide

★ 1

from shawntony

Integrate Claude AI with Google Apps Script to automate tasks in Google Sheets and Gmail.

🔥🔥✓ VerifiedFreeQuick setup

#email #documents

Claude MCP Google Apps Script 연동 완전 가이드

Claude와 Google Apps Script를 MCP(Model Context Protocol)로 연결하여 강력한 업무 자동화 시스템 구축하기

개요

이 가이드는 Claude AI와 Google Apps Script를 MCP 프로토콜을 통해 연결하는 완전한 방법을 제공합니다. 연결 후 다음과 같은 강력한 기능을 사용할 수 있습니다:

🚀 주요 기능

📊 Google Sheets 자동화: 실시간 데이터 읽기/쓰기, 분석, 리포트 생성
📧 Gmail 통합: 스마트 이메일 분류, 자동 응답, 대량 발송
🤖 업무 자동화: 일정 관리, 데이터 분석, 알림 시스템
📈 실시간 대시보드: 여러 데이터 소스 통합 모니터링

시스템 요구사항

필수 준비사항

Google 계정 (Gmail)
Node.js (v18 이상) - 다운로드
Claude Desktop 앱 - 다운로드

설치 확인

node -v    # v18.0.0 이상
npm -v     # 9.0.0 이상

1단계: Google Apps Script 프로젝트 생성

1.1 새 프로젝트 생성

Google Apps Script 접속
"새 프로젝트" 클릭
프로젝트 이름을 **"Claude MCP Server"**로 변경
기본 myFunction() 코드를 모두 삭제

1.2 확인 사항

✅ 프로젝트 이름이 "Claude MCP Server"로 표시
✅ 코드 에디터가 완전히 비어있는 상태

2단계: MCP 서버 코드 작성

2.1 코드 복사 및 붙여넣기

Google Apps Script 에디터에 다음 코드를 복사하여 붙여넣으세요:

/**
 * Claude MCP Server for Google Apps Script
 * 클로드와 구글 워크스페이스를 연결하는 MCP 서버
 */

// MCP 서버 설정
const MCP_CONFIG = {
  name: "google-workspace-mcp",
  version: "1.0.0",
  description: "Google Workspace integration for Claude via MCP",
};

// 도구 목록 정의
const TOOLS = {
  READ_SHEET: {
    name: "read_google_sheet",
    description: "Google Sheets에서 데이터를 읽어옵니다",
    inputSchema: {
      type: "object",
      properties: {
        spreadsheetId: {
          type: "string",
          description: "스프레드시트 ID",
        },
        range: {
          type: "string",
          description: "읽을 범위 (예: A1:C10)",
          default: "A:Z",
        },
      },
      required: ["spreadsheetId"],
    },
  },

  WRITE_SHEET: {
    name: "write_google_sheet",
    description: "Google Sheets에 데이터를 씁니다",
    inputSchema: {
      type: "object",
      properties: {
        spreadsheetId: {
          type: "string",
          description: "스프레드시트 ID",
        },
        range: {
          type: "string",
          description: "쓸 범위 (예: A1:C10)",
        },
        values: {
          type: "array",
          description: "쓸 데이터 (2차원 배열)",
        },
      },
      required: ["spreadsheetId", "range", "values"],
    },
  },

  SEND_EMAIL: {
    name: "send_gmail",
    description: "Gmail을 통해 이메일을 발송합니다",
    inputSchema: {
      type: "object",
      properties: {
        to: {
          type: "string",
          description: "받는 사람 이메일",
        },
        subject: {
          type: "string",
          description: "이메일 제목",
        },
        body: {
          type: "string",
          description: "이메일 내용",
        },
      },
      required: ["to", "subject", "body"],
    },
  },
};

/**
 * MCP 서버 메인 핸들러
 */
function doPost(e) {
  try {
    const request = JSON.parse(e.postData.contents);
    console.log("MCP Request:", request);

    // 요청 타입에 따른 처리
    switch (request.method) {
      case "tools/list":
        return createResponse(handleToolsList());

      case "tools/call":
        return createResponse(handleToolCall(request.params));

      default:
        return createErrorResponse("Unknown method: " + request.method);
    }
  } catch (error) {
    console.error("MCP Error:", error);
    return createErrorResponse("Server error: " + error.message);
  }
}

/**
 * 도구 목록 반환
 */
function handleToolsList() {
  return {
    tools: Object.values(TOOLS),
  };
}

/**
 * 도구 실행
 */
function handleToolCall(params) {
  const { name, arguments: args } = params;

  try {
    switch (name) {
      case "read_google_sheet":
        return readGoogleSheet(args);

      case "write_google_sheet":
        return writeGoogleSheet(args);

      case "send_gmail":
        return sendGmail(args);

      default:
        throw new Error("Unknown tool: " + name);
    }
  } catch (error) {
    return {
      isError: true,
      content: [
        {
          type: "text",
          text: `도구 실행 오류: ${error.message}`,
        },
      ],
    };
  }
}

/**
 * Google Sheets 데이터 읽기
 */
function readGoogleSheet(args) {
  const { spreadsheetId, range = "A:Z" } = args;

  try {
    const spreadsheet = SpreadsheetApp.openById(spreadsheetId);
    const sheet = spreadsheet.getActiveSheet();
    const data = sheet.getRange(range).getValues();

    // 빈 행 제거
    const filteredData = data.filter((row) => row.some((cell) => cell !== ""));

    return {
      content: [
        {
          type: "text",
          text: `스프레드시트 데이터 (${
            filteredData.length
          }행):\n${JSON.stringify(filteredData, null, 2)}`,
        },
      ],
    };
  } catch (error) {
    throw new Error(`Sheets 읽기 실패: ${error.message}`);
  }
}

/**
 * Google Sheets 데이터 쓰기
 */
function writeGoogleSheet(args) {
  const { spreadsheetId, range, values } = args;

  try {
    const spreadsheet = SpreadsheetApp.openById(spreadsheetId);
    const sheet = spreadsheet.getActiveSheet();

    if (values.length > 0) {
      sheet.getRange(range).setValues(values);
    }

    return {
      content: [
        {
          type: "text",
          text: `성공적으로 ${values.length}행의 데이터를 ${range} 범위에 저장했습니다.`,
        },
      ],
    };
  } catch (error) {
    throw new Error(`Sheets 쓰기 실패: ${error.message}`);
  }
}

/**
 * Gmail 이메일 발송
 */
function sendGmail(args) {
  const { to, subject, body } = args;

  try {
    GmailApp.sendEmail(to, subject, body);

    return {
      content: [
        {
          type: "text",
          text: `이메일이 성공적으로 ${to}에게 발송되었습니다.`,
        },
      ],
    };
  } catch (error) {
    throw new Error(`이메일 발송 실패: ${error.message}`);
  }
}

/**
 * 응답 생성 헬퍼
 */
function createResponse(data) {
  return ContentService.createTextOutput(JSON.stringify(data)).setMimeType(
    ContentService.MimeType.JSON
  );
}

function createErrorResponse(message) {
  return ContentService.createTextOutput(
    JSON.stringify({
      error: {
        code: -1,
        message: message,
      },
    })
  ).setMimeType(ContentService.MimeType.JSON);
}

/**
 * 테스트 함수
 */
function testMCPServer() {
  console.log("MCP 서버 테스트 시작");

  // 도구 목록 테스트
  const toolsList = handleToolsList();
  console.log("도구 목록:", toolsList);

  console.log("MCP 서버가 정상적으로 설정되었습니다!");
}

2.2 저장

Ctrl + S 또는 💾 저장 버튼 클릭
문법 오류가 없는지 확인 (빨간 밑줄이 없어야 함)

3단계: 웹 앱 배포

3.1 배포 설정

우상단 "배포" 버튼 클릭
"새 배포" 선택
톱니바퀴 ⚙️ 아이콘 클릭 → "웹 앱" 선택
설정값 입력:
- 설명: "Claude MCP Server v1.0"
- 다음 사용자로 실행: "나"
- 액세스 권한: "모든 사용자"

3.2 권한 승인

"배포" 버튼 클릭
"액세스 승인" 팝업에서 클릭
Google 계정 선택
"고급" → "안전하지 않음(unsafe)" → "이동" 클릭
"허용" 버튼 클릭

3.3 웹 앱 URL 복사

배포 완료 후 나타나는 웹 앱 URL을 복사해서 저장
형태: https://script.google.com/macros/s/ABC...XYZ/exec

4단계: 테스트 스프레드시트 생성

4.1 새 스프레드시트 생성

Google Sheets 접속
"새로 만들기" → "빈 스프레드시트" 클릭
스프레드시트 이름을 **"Claude MCP Test Sheet"**로 변경

4.2 테스트 데이터 입력

A1 셀부터 다음 데이터를 복사해서 붙여넣으세요:

이름	부서	직급	급여
김철수	개발팀	과장	5000
이영희	마케팅팀	대리	4000
박민수	인사팀	차장	6000
최은정	재무팀	사원	3500

4.3 스프레드시트 설정

스프레드시트 ID 복사
- 브라우저 주소창에서 ID 부분 복사
- https://docs.google.com/spreadsheets/d/[이부분이ID]/edit
공유 설정
- 우상단 "공유" 버튼 클릭
- "링크가 있는 모든 사용자" → "편집자" 권한으로 변경
- "완료" 클릭

5단계: MCP 서버 테스트

5.1 기본 테스트

Google Apps Script로 돌아가기
함수 선택 드롭다운에서 testMCPServer 선택
▶️ "실행" 버튼 클릭
권한 승인 (처음 실행시)

5.2 스프레드시트 읽기 테스트

기존 코드 맨 아래에 다음 함수를 추가:

/**
 * 실제 스프레드시트 읽기 테스트
 */
function testReadSheet() {
  const spreadsheetId = "YOUR_SHEET_ID"; // 실제 스프레드시트 ID로 변경

  try {
    const result = readGoogleSheet({
      spreadsheetId: spreadsheetId,
      range: "A1:D10",
    });

    console.log("스프레드시트 읽기 성공!");
    console.log("결과:", result);
  } catch (error) {
    console.error("스프레드시트 읽기 실패:", error);
  }
}

5.3 테스트 실행

testReadSheet 함수 선택 후 실행
실행 로그에서 테스트 데이터가 출력되는지 확인

6단계: 로컬 MCP 클라이언트 설정

6.1 프로젝트 폴더 생성

원하는 위치에 다음 구조로 폴더를 생성하세요:

mkdir claude-gas-mcp
cd claude-gas-mcp
mkdir src
mkdir config

6.2 package.json 생성

프로젝트 루트에 package.json 파일을 생성:

{
  "name": "claude-gas-mcp",
  "version": "1.0.0",
  "description": "Claude와 Google Apps Script 연결을 위한 MCP 클라이언트",
  "main": "src/server.js",
  "type": "module",
  "scripts": {
    "start": "node src/server.js",
    "dev": "node --watch src/server.js"
  },
  "keywords": ["claude", "mcp", "google-apps-script"],
  "author": "",
  "license": "MIT",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^0.4.0",
    "axios": "^1.6.0"
  }
}

6.3 의존성 설치

npm install

6.4 설정 파일 생성

config/mcp-config.json 파일을 생성:

{
  "name": "Google Apps Script MCP Server",
  "version": "1.0.0",
  "description": "Google Workspace와 Claude 연결",
  "config": {
    "webAppUrl": "YOUR_WEB_APP_URL_HERE",
    "testSpreadsheetId": "YOUR_SPREADSHEET_ID_HERE"
  },
  "tools": ["read_google_sheet", "write_google_sheet", "send_gmail"]
}

6.5 MCP 서버 코드 생성

src/server.js 파일을 생성:

#!/usr/bin/env node

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import axios from "axios";
import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// 설정 파일 로드
const configPath = path.join(__dirname, "../config/mcp-config.json");
const config = JSON.parse(fs.readFileSync(configPath, "utf8"));

class GoogleAppsScriptMCPServer {
  constructor() {
    this.server = new Server(
      {
        name: "google-apps-script-mcp",
        version: "1.0.0",
      },
      {
        capabilities: {
          tools: {},
        },
      }
    );

    this.setupToolHandlers();
    this.setupErrorHandling();
  }

  setupErrorHandling() {
    this.server.onerror = (error) => {
      console.error("[MCP Error]", error);
    };

    process.on("SIGINT", async () => {
      await this.server.close();
      process.exit(0);
    });
  }

  setupToolHandlers() {
    // 도구 목록 제공
    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
      return {
        tools: [
          {
            name: "read_google_sheet",
            description: "Google Sheets에서 데이터를 읽어옵니다",
            inputSchema: {
              type: "object",
              properties: {
                spreadsheetId: {
                  type: "string",
                  description: "스프레드시트 ID",
                },
                range: {
                  type: "string",
                  description: "읽을 범위 (예: A1:C10)",
                  default: "A:Z",
                },
              },
              required: ["spreadsheetId"],
            },
          },
          {
            name: "write_google_sheet",
            description: "Google Sheets에 데이터를 씁니다",
            inputSchema: {
              type: "object",
              properties: {
                spreadsheetId: {
                  type: "string",
                  description: "스프레드시트 ID",
                },
                range: {
                  type: "string",
                  description: "쓸 범위 (예: A1:C10)",
                },
                values: {
                  type: "array",
                  description: "쓸 데이터 (2차원 배열)",
                },
              },
              required: ["spreadsheetId", "range", "values"],
            },
          },
          {
            name: "send_gmail",
            description: "Gmail을 통해 이메일을 발송합니다",
            inputSchema: {
              type: "object",
              properties: {
                to: {
                  type: "string",
                  description: "받는 사람 이메일",
                },
                subject: {
                  type: "string",
                  description: "이메일 제목",
                },
                body: {
                  type: "string",
                  description: "이메일 내용",
                },
              },
              required: ["to", "subject", "body"],
            },
          },
        ],
      };
    });

    // 도구 실행
    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
      const { name, arguments: args } = request.params;

      try {
        switch (name) {
          case "read_google_sheet":
            return await this.readGoogleSheet(args);

          case "write_google_sheet":
            return await this.writeGoogleSheet(args);

          case "send_gmail":
            return await this.sendGmail(args);

          default:
            throw new Error(`알 수 없는 도구: ${name}`);
        }
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `오류 발생: ${error.message}`,
            },
          ],
          isError: true,
        };
      }
    });
  }

  async callGoogleAppsScript(toolName, params) {
    const payload = {
      method: "tools/call",
      params: {
        name: toolName,
        arguments: params,
      },
    };

    try {
      console.log(`[MCP] Google Apps Script 호출: ${toolName}`, params);

      const response = await axios.post(config.config.webAppUrl, payload, {
        headers: {
          "Content-Type": "application/json",
        },
        timeout: 30000,
      });

      console.log(`[MCP] 응답 받음:`, response.data);
      return response.data;
    } catch (error) {
      console.error(`[MCP] 요청 실패:`, error.message);
      throw new Error(`Google Apps Script 호출 실패: ${error.message}`);
    }
  }

  async readGoogleSheet(args) {
    const result = await this.callGoogleAppsScript("read_google_sheet", args);

    return {
      content: [
        {
          type: "text",
          text: result.content?.[0]?.text || "데이터를 읽어왔습니다.",
        },
      ],
    };
  }

  async writeGoogleSheet(args) {
    const result = await this.callGoogleAppsScript("write_google_sheet", args);

    return {
      content: [
        {
          type: "text",
          text: result.content?.[0]?.text || "데이터를 저장했습니다.",
        },
      ],
    };
  }

  async sendGmail(args) {
    const result = await this.callGoogleAppsScript("send_gmail", args);

    return {
      content: [
        {
          type: "text",
          text: result.content?.[0]?.text || "이메일을 발송했습니다.",
        },
      ],
    };
  }

  async run() {
    const transport = new StdioServerTransport();
    await this.server.connect(transport);

    console.error("Google Apps Script MCP 서버가 시작되었습니다.");
    console.error(`웹 앱 URL: ${config.config.webAppUrl}`);
    console.error(
      "사용 가능한 도구: read_google_sheet, write_google_sheet, send_gmail"
    );
  }
}

// 서버 시작
const server = new GoogleAppsScriptMCPServer();
server.run().catch(console.error);

6.6 테스트 스크립트 생성

src/test.js 파일을 생성:

import axios from "axios";
import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// 설정 파일 로드
const configPath = path.join(__dirname, "../config/mcp-config.json");
const config = JSON.parse(fs.readFileSync(configPath, "utf8"));

async function testGoogleAppsScript() {
  console.log("🧪 Google Apps Script MCP 연결 테스트 시작\n");

  // 테스트 1: 스프레드시트 읽기
  console.log("📊 테스트 1: 스프레드시트 데이터 읽기");
  try {
    const readPayload = {
      method: "tools/call",
      params: {
        name: "read_google_sheet",
        arguments: {
          spreadsheetId: config.config.testSpreadsheetId,
          range: "A1:D10",
        },
      },
    };

    const readResponse = await axios.post(
      config.config.webAppUrl,
      readPayload,
      {
        headers: { "Content-Type": "application/json" },
        timeout: 10000,
      }
    );

    console.log("✅ 스프레드시트 읽기 성공!");
    console.log("📋 응답:", readResponse.data);
  } catch (error) {
    console.log("❌ 스프레드시트 읽기 실패:", error.message);
  }

  console.log("\n🎉 테스트 완료!");
}

// 테스트 실행
testGoogleAppsScript().catch(console.error);

6.7 연결 테스트

node src/test.js

7단계: Claude Desktop 연결

7.1 Claude Desktop 설정 파일 수정

Windows에서 설정 파일 위치:

%APPDATA%\Claude\claude_desktop_config.json

7.2 설정 파일 내용

기존 설정에 다음 내용을 추가:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\[사용자명]\\Desktop"
      ],
      "env": {}
    },
    "google-apps-script": {
      "command": "node",
      "args": ["C:\\[프로젝트경로]\\claude-gas-mcp\\src\\server.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  },
  "darkMode": "dark",
  "scale": 0,
  "locale": "ko-KR"
}

7.3 Claude Desktop 재시작

Claude Desktop 앱을 완전히 종료
앱을 다시 시작
새 대화 시작

7.4 연결 테스트

Claude Desktop에서 다음과 같이 테스트:

Google Apps Script MCP 서버가 연결되었는지 확인하고,
스프레드시트 ID [YOUR_SHEET_ID]의 데이터를 읽어서 보여줘.

사용 예시

📊 기본 데이터 조작

스프레드시트 읽기

"스프레드시트 ID 13Qy45cJ6oDJsyS007bml2GAyklGAiY7EGd1GZ1vO7ro에서
직원 데이터를 읽어서 부서별 평균 급여를 계산해줘"

데이터 추가

"새 직원 정보를 추가해줘:
이름-홍길동, 부서-IT팀, 직급-사원, 급여-3200"

이메일 발송

"부서별 급여 현황을 요약해서 manager@company.com으로 보내줘"

🤖 고급 자동화 요청

업무 자동화 함수 생성

"매일 아침 8시에 전날 매출 데이터를 분석해서
이메일로 보내주는 GAS 함수를 만들어줘"

스마트 이메일 시스템

"Gmail에서 특정 키워드가 포함된 이메일을 자동으로 분류하고
적절한 템플릿으로 답변하는 함수를 만들어줘"

결과: 클로드가 키워드 기반 분류 알고리즘, 자동 응답 시스템, 라벨링 기능을 포함한 완전한 이메일 자동화 시스템을 생성합니다.

실시간 대시보드

"여러 시트의 데이터를 종합해서 실시간 대시보드를
만들어주는 함수를 작성해줘"

결과: 다중 데이터 소스를 통합하여 실시간 업데이트되는 HTML 대시보드와 자동 갱신 시스템을 구축합니다.

데이터 분석 자동화

"매출 데이터를 분석해서 트렌드 예측하고
인사이트를 요약해서 경영진에게 보고하는 시스템을 만들어줘"

결과: 통계 분석, 예측 모델링, 시각화 차트, 자동 리포트 생성 기능을 포함한 BI 시스템을 구축합니다.