MCP Google Sheets Server

Claude Desktop, Claude Code 및 모든 Model Context Protocol (MCP) 호환 AI 클라이언트에서 Google Sheets를 읽고, 쓰고, 관리하세요.

Google Sheets API를 Claude 및 기타 LLM 에이전트에 노출하는 가볍고 프로덕션에 바로 사용할 수 있는 Model Context Protocol (MCP) 서버입니다. 스프레드시트 워크플로를 자동화하고, 시트에 기록하는 AI 에이전트 도구를 구축하고, 팀의 스프레드시트와 데이터 파이프라인을 동기화하거나, Claude가 문서를 편집하도록 할 수 있습니다. 단 하나의 MCP 서버로 가능합니다.

목차

• 왜 필요한가

• 기능

• 빠른 시작

• 설정

  • 1. Google Cloud 프로젝트 생성

  • 2. Sheets API 사용 설정

  • 3. OAuth 2.0 사용자 인증 정보 만들기

  • 4. 서버 설치

  • 5. 인증

• MCP 클라이언트에 등록

  • Claude Desktop

  • Claude Code

• 사용 가능한 도구

• 사용 예시

• 설정

• 보안

• 문제 해결

• 개발

• 라이선스

왜 필요한가

Claude가 Google Sheet를 업데이트하도록 하고 싶다면 — 작업 추적기, 습관 기록, 프로젝트 대시보드 — 창을 전환하지 않고도 이 서버가 필요한 도구를 제공합니다. 이는 Anthropic의 공식 Google Drive MCP 커넥터(파일을 읽을 수는 있지만 셀을 쓸 수는 없음)의 자연스러운 대응물입니다.

일반적인 워크플로:

• 지원할 때 Claude가 구직 지원 추적 시트에 행을 추가하도록 함

• 연구 독서 목록, 주간 회고, IELTS 학습 로그 동기화

• AI 에이전트에게 구조화되고 감사 가능한 출력을 스프레드시트로 제공

• 자연어 프롬프트로 재무 또는 운영 대시보드 자동화

기능

• ✅ 읽기 A1 표기법의 모든 범위

• ✅ 업데이트 RAW 또는 USER_ENTERED 구문 분석으로 셀 값

• ✅ 추가 모든 시트에 행 추가 (로깅에 이상적)

• ✅ 지우기 서식 삭제 없이 범위 지우기

• ✅ 일괄 업데이트 한 번의 호출로 여러 범위 업데이트

• ✅ 검사 스프레드시트 메타데이터 (시트 탭, 차원)

• 🔐 OAuth 2.0 로컬 토큰 저장 및 자동 갱신

• 📦 TypeScript, ES 모듈, 최소한의 종속성

• 🖥️ Claude Desktop, Claude Code 및 stdio를 통한 모든 MCP 클라이언트와 작동

빠른 시작

# 1. Clone
git clone https://github.com/yangchoi/mcp-google-sheets.git
cd mcp-google-sheets

# 2. Install and build
npm install
npm run build

# 3. Put your Google Cloud OAuth credentials.json here
mkdir -p ~/.config/mcp-google-sheets
cp /path/to/downloaded-credentials.json ~/.config/mcp-google-sheets/credentials.json

# 4. Authorize (opens browser once)
npm run auth

# 5. Register with Claude — see below

설정

1. Google Cloud 프로젝트 생성

• Google Cloud Console을 엽니다.

• 새 프로젝트를 클릭하고 원하는 이름을 지정합니다 (예: mcp-sheets).

2. Sheets API 사용 설정

• 프로젝트에서 Google Sheets API를 엽니다.

• 사용 설정을 클릭합니다.

3. OAuth 2.0 사용자 인증 정보 만들기

• 사용자 인증 정보를 엽니다.

• 사용자 인증 정보 만들기 → OAuth 클라이언트 ID를 클릭합니다.

• 메시지가 표시되면 먼저 OAuth 동의 화면을 구성합니다:

  • 사용자 유형: 외부 (내부를 사용할 수 있는 Workspace가 아닌 경우)

  • 앱이 테스트 모드에 있는 동안 자신을 테스트 사용자로 추가합니다.

  • 범위는 동의 화면에서 비워 둘 수 있습니다. 앱이 런타임에 요청합니다.

• OAuth 클라이언트 ID 만들기로 돌아가서:

  • 애플리케이션 유형: 데스크톱 앱

  • 이름: 아무거나 (예: mcp-google-sheets)

• JSON 다운로드를 클릭하고 저장합니다. 이것이 credentials.json입니다.

파일을 기본 구성 디렉터리로 이동합니다:

mkdir -p ~/.config/mcp-google-sheets
mv ~/Downloads/client_secret_*.json ~/.config/mcp-google-sheets/credentials.json

(또는 GOOGLE_SHEETS_CREDENTIALS_PATH를 설정하여 다른 위치를 가리킬 수 있습니다 — 설정 참조.)

4. 서버 설치

git clone https://github.com/yangchoi/mcp-google-sheets.git
cd mcp-google-sheets
npm install
npm run build

5. 인증

일회성 OAuth 흐름을 실행합니다. 브라우저가 열리고, 자신의 Sheets에 대한 액세스를 승인하면 결과 토큰이 ~/.config/mcp-google-sheets/token.json에 저장됩니다.

npm run auth

터미널에 Authorization complete. Token saved.가 표시되어야 합니다.

MCP 클라이언트에 등록

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json (Windows)을 편집하고 다음을 추가합니다:

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

Claude Desktop을 다시 시작합니다. Sheets 도구가 도구 선택기에 나타납니다.

Claude Code

Claude Code MCP 구성에 추가합니다 (일반적으로 ~/.claude/settings.json의 mcpServers 아래):

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

Claude Code를 다시 시작합니다. /mcp를 통해 도구가 로드되는지 확인합니다.

사용 가능한 도구

모든 도구는 spreadsheetId (시트 URL에서 /d/와 /edit 사이에 있음)를 받습니다.

사용 예시

Claude에게 프롬프트:

"스프레드시트 1abcXYZ...를 보고 Applications 시트에 새 행을 추가하세요: Legora, Stockholm, Legal AI, 2026-08-18, pending."

Claude는 get_spreadsheet_metadata를 호출하여 시트를 찾은 다음 append_row로 값을 추가합니다.

또는 읽기 + 요약:

"1abcXYZ...의 Applications 시트에서 처음 20행을 읽고 아직 보류 중인 항목이 몇 개인지 알려주세요."

Claude는 Applications!A1:F20에 대해 read_range를 호출한 다음 반환된 배열을 분석합니다.

설정

환경 변수 (모두 선택 사항):

보안

• credentials.json 및 token.json은 로컬 전용이며 Google의 OAuth 서버를 제외한 어디로도 전송되지 않습니다.

• 두 파일 모두 .gitignore에 포함되어 있습니다. 버전 관리에 커밋하지 마십시오.

• 서버는 spreadsheets 범위만 요청합니다 — Drive 전체 액세스, Gmail, 캘린더는 없습니다.

• 토큰 갱신은 자동으로 이루어집니다. 장기 액세스 토큰이 노출되지 않습니다.

• 서버를 실행하는 데 정상 상태에서 네트워크 수신 포트가 필요하지 않습니다 (임시 포트 47319는 초기 OAuth 콜백 중에만 사용되며 즉시 닫힙니다).

문제 해결

credentials.json not found — 3-4단계를 놓쳤습니다. 경로를 확인하세요.

OAuth 중 Error: access_denied — Google 계정이 OAuth 동의 화면에 테스트 사용자로 등록되지 않았습니다. OAuth 동의 화면으로 이동하여 테스트 사용자 아래에 이메일을 추가하세요.

도구 호출 시 insufficient permission — 토큰이 더 작은 범위로 생성되었습니다. token.json을 삭제하고 npm run auth를 다시 실행하세요.

Claude에 도구가 나타나지 않음 — MCP 구성의 경로가 절대 경로이고 dist/index.js를 가리키는지 확인하세요 (src/index.ts가 아님). npm run build를 실행했는지 확인하세요.

서버 시작 시 No stored token — 5단계를 건너뛰었습니다. npm run auth를 실행하세요.

개발

npm install
npm run dev      # tsc --watch
npm run build    # produces dist/
npm run start    # runs dist/index.js on stdio

기여를 환영합니다. 이는 최소한의 핵심입니다. 구조적 업데이트 (spreadsheets.batchUpdate를 통한 서식, 시트 추가, 필터, 보호된 범위)에 대한 PR을 환영합니다.

라이선스

MIT