gsheets-mcp

Claude가 Google Sheets API v4를 통해 Google Sheets를 읽고 쓸 수 있게 해주는 로컬 MCP(Model Context Protocol) 서버입니다.

전적으로 사용자 자신의 머신에서 실행됩니다. OAuth2("설치된 앱" / 데스크톱 흐름)를 사용해 자신의 Google 계정으로 인증하며, 데이터가 제3자 서버를 거치지 않습니다.

MIT 라이선스 하에 무료 및 오픈소스입니다. 텔레메트리 없음, 제3자 서버 없음.

🌐 웹사이트: https://gsheets-mcp.trombella.org/

제공 기능

대부분의 도구는 스프레드시트 ID를 받습니다 — 시트 URL의 긴 문자열: https://docs.google.com/spreadsheets/d/<THIS_IS_THE_ID>/edit. 직접 복사하는 대신 list_spreadsheets로 ID를 찾을 수도 있습니다.

Related MCP server: sheetsdb-mcp-server

사전 요구 사항

• Node.js 18 이상 (node --version).

• Google 계정.

1부 — Google Cloud 설정(1회)

서버가 시트 접근 권한을 요청할 수 있도록 OAuth "데스크톱 앱" 클라이언트가 필요합니다.

1. Google Cloud 프로젝트 만들기

1. https://console.cloud.google.com/로 이동합니다.

2. 상단 바 → 프로젝트 드롭다운 → 새 프로젝트. 이름(예: gsheets-mcp)을 지정하고 생성합니다. 선택되어 있는지 확인합니다.

2. API 사용 설정

1. API 및 서비스 → 라이브러리(https://console.cloud.google.com/apis/library)로 이동합니다.

2. Google Sheets API를 검색하여 열고 사용을 클릭합니다.

3. Google Drive API를 검색하여 열고 사용을 클릭합니다.

Drive API는 list_spreadsheets가 시트를 나열할 때 만 사용되며, 읽기 전용 drive.readonly 범위를 통해 사용됩니다. 파일을 수정, 이동 또는 삭제하는 데는 사용되지 않습니다.

3. OAuth 동의 화면 구성

1. API 및 서비스 → OAuth 동의 화면으로 이동합니다.

2. 사용자 유형: 외부 → 만들기. (내부는 Google Workspace 조직에서만 사용할 수 있습니다.)

3. 필수 필드를 입력합니다: 앱 이름(예: gsheets-mcp), 사용자 지원 이메일 및 개발자 연락처로 자신의 이메일. 나머지는 비워 둘 수 있습니다. 저장 후 계속을 클릭합니다.

4. 범위: 여기서 범위를 추가하지 않아도 됩니다(앱이 로그인 시 요청합니다). 저장 후 계속을 클릭합니다.

5. 테스트 사용자: 사용자 추가를 클릭하고 자신의 Google 이메일을 추가합니다. 필수입니다 — "테스트" 모드에서는 나열된 테스트 사용자만 앱을 승인할 수 있습니다. 저장 후 계속을 클릭합니다.

6. 앱을 테스트 모드로 둡니다. 개인용으로는 충분하며, 자신의 테스트 사용자 계정에는 만료되지 않습니다. ("프로덕션"으로 게시하면 Google의 앱 검증이 트리거되지만 여기서는 필요하지 않습니다.)

4. OAuth 클라이언트 자격 증명 만들기

1. API 및 서비스 → 사용자 인증 정보로 이동합니다.

2. 사용자 인증 정보 만들기 → OAuth 클라이언트 ID.

3. 애플리케이션 유형: 데스크톱 앱. 이름을 지정합니다(예: gsheets-mcp desktop). 만들기를 클릭합니다.

4. 확인 대화상자에서 JSON 다운로드를 클릭합니다. 이 파일에는 client_id와 client_secret이 들어 있습니다.

5. 자격 증명 파일 배치

다운로드한 파일을 구성 디렉터리에 credentials.json 으로 저장합니다:

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

이 파일은 비공개로 유지하세요 — git에서 무시됩니다. GSHEETS_MCP_CREDENTIALS 환경 변수로 위치를 재정의할 수 있습니다(.env.example 참조).

2부 — 설치 및 빌드

프로젝트 폴더에서:

npm install
npm run build

3부 — 로그인(1회)

대화형 로그인을 실행합니다. 브라우저에서 Google 동의 화면이 열립니다. 접근을 승인하면 토큰이 ~/.config/gsheets-mcp/token.json에 저장됩니다(이후 자동으로 갱신됨).

npm run login
# equivalently: node dist/index.js login

앱이 테스트 모드이므로 Google에 "Google에서 이 앱을 확인하지 않았습니다" 경고가 표시됩니다. 자신의 앱에서는 정상입니다 — 고급 → gsheets-mcp(안전하지 않음)로 이동을 클릭하고 계속합니다. 그런 다음 요청된 두 가지 권한을 부여합니다(아래 참조).

터미널에 ✅ Authorization complete가 표시되면 완료입니다.

요청되는 범위:

• https://www.googleapis.com/auth/spreadsheets — 스프레드시트 읽기/쓰기.

• https://www.googleapis.com/auth/drive.readonly — 읽기 전용, list_spreadsheets가 시트를 나열할 때 만 사용됩니다. 파일을 수정하거나 삭제할 수 없습니다.

언제든지 접근을 취소하려면 https://myaccount.google.com/permissions를 방문하세요.

참고: 서버를 업그레이드하고 요청 범위가 변경된 경우 npm run login을 다시 실행해야 합니다 — 이전에 부여된 동의는 새 범위를 포함하지 않습니다. 머신별로도 동일합니다(각 컴퓨터는 자체 토큰을 저장합니다).

4부 — Claude Desktop에 서버 추가

Claude Desktop의 구성 파일을 엽니다:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

mcpServers 아래에 gsheets 항목을 추가하고 컴파일된 진입점을 가리키게 합니다. 이 프로젝트의 dist/index.js에 대한 절대 경로를 사용하세요:

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

파일을 저장하고 Claude Desktop을 완전히 종료한 후 다시 엽니다. 이제 gsheets 도구가 표시되어야 합니다. Claude에게 다음과 같이 요청해 보세요:

"내 Google Sheets를 나열한 다음 'Budget'이라는 시트에서 A1:C5를 읽어줘."

Claude Code와 함께 사용하기

claude mcp add gsheets -- node /absolute/path/to/google-sheets-mcp/dist/index.js

사용 예시(Claude에게 요청할 내용)

• 목록: "내 Google Sheets를 나열해줘" / "이름에 'budget'이 포함된 내 스프레드시트를 찾아줘."

• 정보: "스프레드시트 <ID>에는 어떤 탭이 있어?" (정확한 탭 이름을 반환합니다).

• 읽기: "스프레드시트 <ID>에서 범위 Foglio1!A1:D10을 읽어줘."

• 업데이트: "스프레드시트 <ID>의 Foglio1!A1부터 값 [[\"Name\",\"Score\"],[\"Ada\",42]]을 넣어줘."

• 추가: "스프레드시트 <ID>의 Foglio1에 행 [\"Grace\", 99]을 추가해줘."

⚠️ 참고: 탭 이름은 지역화되어 있습니다

범위는 탭(시트) 이름을 사용합니다(예: Sheet1!A1:D10). 하지만 기본 탭 이름은 Google 계정의 언어에 따라 다릅니다: 영어는 Sheet1, 이탈리아어는 Foglio1, 스페인어는 Hoja1, 프랑스어는 Feuille1 등입니다. 잘못된 이름을 사용하면 Unable to parse range: … 오류가 반환됩니다.

실제 탭 이름이 확실하지 않으면 시트를 열고 하단의 탭 라벨을 읽거나, 범위로 탭 이름만 전달하여 (예: Foglio1) Claude에게 전체 시트를 읽도록 요청하세요. 정확한 탭 이름을 나열하는 전용 get_sheet_info 도구가 로드맵에 있습니다.

구성 참조

모두 선택 사항입니다. 기본값으로 바로 작동합니다. .env.example을 참조하세요.

헤드리스 / HTTP 모드(아래 참조)에서는 환경 변수로 자격 증명을 제공할 수 있습니다:

원격 / 모바일 사용(고급)

기본 전송 방식은 stdio(로컬)입니다. 서버는 HTTP를 통한 원격 MCP 커넥터로도 실행할 수 있어 로컬 프로세스를 실행할 수 없는 클라이언트(예: Claude 모바일 앱)에서 접근할 수 있습니다:

MCP_AUTH_TOKEN=$(openssl rand -hex 32) npm run serve:http   # listens on :8000/mcp

모든 요청은 Authorization: Bearer <MCP_AUTH_TOKEN>을 보내야 합니다. 이 엔드포인트는 스프레드시트를 쓸 수 있으므로, 항상 Bearer 토큰 외에도 네트워크 게이트(Cloudflare Access, VPN) 뒤에 두어야 합니다 — 인터넷에 원시적으로 노출하지 마세요.

개인 상시 운영 설정(Cloudflare Tunnel 뒤)을 위한 준비된 Home Assistant OS 애드온이 ha-addon/gsheets-mcp/에 있습니다 — 전체 단계별 가이드는 DOCS.md를 참조하세요.

문제 해결

• "Not authenticated. Run the one-time login first" — 아직 로그인하지 않았거나 토큰 파일이 없습니다. npm run login을 실행하세요.

• "OAuth client credentials not found" — credentials.json이 서버가 예상하는 위치에 없습니다. 1부 5단계를 확인하세요.

• 브라우저에서 403 access_denied — Google 계정이 테스트 사용자로 등록되지 않았습니다. OAuth 동의 화면 → 테스트 사용자에서 추가하세요(1부 3.5단계).

• "Request had insufficient authentication scopes" — 저장된 토큰이 범위 변경 이전의 것입니다(예: list_spreadsheets에는 drive.readonly가 필요). npm run login을 다시 실행하여 재동의하세요.

• Unable to parse range: … — 탭 이름이 잘못되었습니다. 탭 이름은 지역화되어 있습니다 (이탈리아어 Foglio1, 영어 Sheet1). get_sheet_info를 사용하여 정확한 이름을 확인하세요.

• refresh_token 없음 경고 — https://myaccount.google.com/permissions에서 앱을 취소하고 npm run login을 다시 실행하세요.

• Claude Desktop에 도구가 표시되지 않음 — claude_desktop_config.json의 경로가 절대 경로이고 dist/index.js를 가리키는지, npm run build를 실행했는지, Claude Desktop을 완전히 다시 시작했는지 확인하세요.

개발

npm run build       # compile to dist/
npm run watch       # recompile on change
npm run typecheck   # type-check without emitting

소스 구조: src/index.ts(진입점), src/auth.ts(OAuth), src/sheetsClient.ts 및 src/driveClient.ts(API 래퍼), src/tools/*(MCP 도구당 파일 하나).

라이선스

MIT 라이선스로 배포됩니다. 자유롭게 사용, 수정, 배포할 수 있습니다. 시간을 절약해 준다면 커피 한 잔으로 개발을 지원할 수 있습니다 — 링크는 웹사이트를 참조하세요. ☕

Google과 제휴하거나 보증하지 않습니다. "Google Sheets"는 Google LLC의 상표입니다.