mcp-google-sheet

🤔 이게 뭔가요?

mcp-google-sheets는 Python 기반 MCP 서버로, MCP 호환 클라이언트(예: Claude Desktop)와 Google Sheets API 사이의 브리지 역할을 합니다. 정의된 도구 세트를 사용하여 Google 스프레드시트와 상호작용할 수 있으며, AI 기반의 강력한 자동화 및 데이터 조작 워크플로우를 가능하게 합니다.

Related MCP server: mcp-google-sheets

🚀 빠른 시작 (uvx 사용)

기본적으로 서버는 한 줄로 실행됩니다: uvx mcp-google-sheets@latest.

이 명령은 최신 코드를 자동으로 다운로드하여 실행합니다. 항상 @latest를 사용할 것을 권장합니다. 최신 기능과 버그 수정이 포함된 최신 버전을 보장받을 수 있습니다.

아래에서 사용되는 ID에 대한 자세한 내용은 ID 참조 가이드를 참조하세요.

1. ☁️ 사전 준비: Google Cloud 설정

   • 먼저 Google Cloud Platform 자격 증명을 구성하고 필요한 API를 활성화해야 합니다. 서비스 계정(Service Account) 사용을 강력히 권장합니다.

   • ➡️ 아래의 상세 Google Cloud Platform 설정 가이드로 이동하세요.

2. 🐍 uv 설치

   • uvx는 빠른 Python 패키지 설치 및 해석 도구인 uv의 일부입니다. 아직 설치하지 않았다면 설치하세요:

     # macOS / Linux
     curl -LsSf https://astral.sh/uv/install.sh | sh
     # Windows
     powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
     # Or using pip:
     # pip install uv

     필요한 경우 설치 프로그램 출력의 지침에 따라 uv를 PATH에 추가하세요.

3. 🔑 필수 환경 변수 설정 (서비스 계정 권장)

   • 서버에 인증 방법을 알려줘야 합니다. 터미널에서 다음 변수를 설정하세요:

   • (Linux/macOS)

     # Replace with YOUR actual path and folder ID from the Google Setup step
     export SERVICE_ACCOUNT_PATH="/path/to/your/service-account-key.json"
     export DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"

   • (Windows CMD)

     set SERVICE_ACCOUNT_PATH="C:\path\to\your\service-account-key.json"
     set DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"

   • (Windows PowerShell)

     $env:SERVICE_ACCOUNT_PATH = "C:\path\to\your\service-account-key.json"
     $env:DRIVE_FOLDER_ID = "YOUR_DRIVE_FOLDER_ID"

   • ➡️ 다른 옵션(OAuth, CREDENTIALS_CONFIG)은 상세 인증 및 환경 변수를 참조하세요.

4. 🏃 서버 실행!

   • uvx가 최신 버전의 mcp-google-sheets를 자동으로 다운로드하여 실행합니다:

     uvx mcp-google-sheets@latest

   • 서버가 시작되고 준비 완료를 알리는 로그를 출력합니다.

   • 💡 프로 팁: 항상 @latest를 사용하여 버그 수정과 기능이 포함된 최신 버전을 받으세요. @latest 없이 사용하면 uvx가 캐시된 이전 버전을 사용할 수 있습니다.

5. 🔌 MCP 클라이언트 연결

   • 사용 중인 클라이언트(예: Claude Desktop)가 실행 중인 서버에 연결하도록 구성하세요.

   • 사용하는 클라이언트에 따라 4단계가 필요하지 않을 수 있습니다. 클라이언트가 서버를 직접 실행할 수 있기 때문입니다. 하지만 제대로 설정되었는지 확인하기 위해 4단계를 테스트 실행해 보는 것이 좋은 습관입니다.

   • ➡️ 예시는 Claude Desktop에서 사용하기를 참조하세요.

6. ⚡ 선택 사항: 도구 필터링 활성화 (컨텍스트 사용량 줄이기)

   • 기본적으로 19개 도구가 모두 활성화되어 있습니다(~13K 토큰). 컨텍스트 사용량을 줄이려면 필요한 도구만 활성화하세요.

   • ➡️ 자세한 내용은 도구 필터링을 참조하세요.

준비 완료! MCP 클라이언트를 통해 명령을 실행하세요.

✨ 주요 기능

• 원활한 통합: Google Drive 및 Google Sheets API에 직접 연결합니다.

• 포괄적인 도구: 다양한 작업(CRUD, 목록 조회, 일괄 처리, 공유, 서식 지정 등)을 제공합니다.

• 유연한 인증: 서비스 계정(권장), OAuth 2.0, 환경 변수를 통한 직접 자격 증명 주입을 지원합니다.

• 간편한 배포: uvx로 즉시 실행(설치 없이 사용)하거나 uv를 사용하여 개발용으로 클론할 수 있습니다.

• AI 지원: MCP 호환 클라이언트와 함께 사용하도록 설계되어 자연어로 스프레드시트를 조작할 수 있습니다.

• 도구 필터링: --include-tools 또는 ENABLED_TOOLS 환경 변수로 필요한 도구만 활성화하여 컨텍스트 창 사용량을 줄일 수 있습니다.

🎯 도구 필터링 (컨텍스트 사용량 줄이기)

문제: 기본적으로 이 MCP 서버는 19개 도구를 모두 노출하여 대화가 시작되기 전에 ~13,000 토큰을 소비합니다. 몇 개의 도구만 필요하다면 이는 귀중한 컨텍스트 창 공간을 낭비하는 것입니다.

해결책: 도구 필터링을 사용하여 실제로 사용하는 도구만 활성화하세요.

도구 필터링 활성화 방법

다음 두 가지 방법으로 도구를 필터링할 수 있습니다:

1. 명령줄 인자 --include-tools:

   {
     "mcpServers": {
       "google-sheets": {
         "command": "uvx",
         "args": [
           "mcp-google-sheets@latest",
           "--include-tools",
           "get_sheet_data,update_cells,list_spreadsheets,list_sheets"
         ],
         "env": {
           "SERVICE_ACCOUNT_PATH": "/path/to/credentials.json"
         }
       }
     }
   }

2. 환경 변수 ENABLED_TOOLS:

   {
     "mcpServers": {
       "google-sheets": {
         "command": "uvx",
         "args": ["mcp-google-sheets@latest"],
         "env": {
           "SERVICE_ACCOUNT_PATH": "/path/to/credentials.json",
           "ENABLED_TOOLS": "get_sheet_data,update_cells,list_spreadsheets,list_sheets"
         }
       }
     }
   }

사용 가능한 도구 이름

필터링 시 다음 정확한 도구 이름을 사용하세요(쉼표로 구분, 공백 없음):

가장 일반적인 도구 (권장 하위 집합):

• get_sheet_data - 스프레드시트에서 읽기

• update_cells - 스프레드시트에 쓰기

• list_spreadsheets - 스프레드시트 찾기

• list_sheets - 탭 탐색

모든 사용 가능한 도구:

• add_columns

• add_rows

• batch_update

• batch_update_cells

• copy_sheet

• create_sheet

• create_spreadsheet

• find_in_spreadsheet

• get_multiple_sheet_data

• get_multiple_spreadsheet_summary

• get_sheet_data

• get_sheet_formulas

• list_folders

• list_sheets

• list_spreadsheets

• rename_sheet

• search_spreadsheets

• share_spreadsheet

• update_cells

참고: --include-tools 또는 ENABLED_TOOLS가 모두 지정되지 않으면 모든 도구가 활성화됩니다(기본 동작).

🛠️ 사용 가능한 도구 및 리소스

이 서버는 Google Sheets와 상호작용하기 위한 다음 도구를 제공합니다:

아래에서 사용되는 ID에 대한 자세한 내용은 ID 참조 가이드를 참조하세요.

(입력 매개변수는 별도로 명시되지 않는 한 일반적으로 문자열입니다)

• list_spreadsheets: 구성된 Drive 폴더(서비스 계정) 또는 사용자가 접근 가능한(OAuth) 스프레드시트를 나열합니다.

  • folder_id (선택적 문자열): 검색할 Google Drive 폴더 ID. URL에서 가져옵니다. 생략하면 구성된 기본 폴더를 사용하거나 'My Drive'를 검색합니다.

  • 반환값: 객체 목록 [{id: string, title: string}]

• create_spreadsheet: 새 스프레드시트를 생성합니다.

  • title (문자열): 스프레드시트의 원하는 제목. 예: "Quarterly Report Q4".

  • folder_id (선택적 문자열): 스프레드시트를 생성할 Google Drive 폴더 ID. URL에서 가져옵니다. 생략하면 구성된 기본 폴더 또는 루트를 사용합니다.

  • 반환값: spreadsheetId, title, folder를 포함한 스프레드시트 정보 객체.

• get_sheet_data: 시트/탭의 범위에서 데이터를 읽습니다.

  • spreadsheet_id (문자열): 스프레드시트 ID (URL에서 가져옴).

  • sheet (문자열): 시트/탭 이름 (예: "Sheet1").

  • range (선택적 문자열): A1 표기법 (예: 'A1:C10', 'Sheet1!B2:D'). 생략하면 sheet로 지정된 전체 시트/탭을 읽습니다.

  • include_grid_data (선택적 부울, 기본값 False): True이면 서식 및 메타데이터를 포함한 전체 그리드 데이터를 반환합니다(훨씬 큼). False이면 값만 반환합니다(더 효율적).

  • 반환값: include_grid_data=True이면 메타데이터가 포함된 전체 그리드 데이터(get 응답). False이면 Values API의 값 결과 객체(values.get 응답).

• get_sheet_formulas: 시트/탭의 범위에서 수식을 읽습니다.

  • spreadsheet_id (문자열): 스프레드시트 ID (URL에서 가져옴).

  • sheet (문자열): 시트/탭 이름 (예: "Sheet1").

  • range (선택적 문자열): A1 표기법 (예: 'A1:C10', 'Sheet1!B2:D'). 생략하면 sheet로 지정된 시트/탭의 모든 수식을 읽습니다.

  • 반환값: 셀 수식의 2D 배열(배열의 배열) (values.get 응답).

• update_cells: 특정 범위에 데이터를 씁니다. 기존 데이터를 덮어씁니다.

  • spreadsheet_id (문자열): 스프레드시트 ID (URL에서 가져옴).

  • sheet (문자열): 시트/탭 이름 (예: "Sheet1").

  • range (문자열): 쓸 A1 표기법 범위 (예: 'A1:C3').

  • data (배열의 배열): 쓸 값의 2D 배열. 예: [[1, 2, 3], ["a", "b", "c"]].

  • 반환값: 업데이트 결과 객체 (values.update 응답).

• batch_update_cells: 한 번의 API 호출로 여러 범위를 업데이트합니다.

  • spreadsheet_id (문자열): 스프레드시트 ID (URL에서 가져옴).

  • sheet (문자열): 시트/탭 이름 (예: "Sheet1").

  • ranges (객체): 범위 문자열(A1 표기법)을 값의 2D 배열에 매핑하는 사전. 예: { "A1:B2": [[1, 2], [3, 4]], "D5": [["Hello"]] }.

  • 반환값: 작업 결과 (values.batchUpdate 응답).

• add_rows: 지정된 인덱스에 시트/탭에 빈 행을 추가(삽입)합니다.

  • spreadsheet_id (문자열): 스프레드시트 ID (URL에서 가져옴).

  • sheet (문자열): 시트/탭 이름 (예: "Sheet1").

  • count (정수): 삽입할 빈 행 수.

  • start_row (선택적 정수, 기본값 0): 행 삽입을 시작할 0 기반 행 인덱스. 생략하면 0(시작 부분에 삽입)으로 기본 설정됩니다.

  • 반환값: 작업 결과 (batchUpdate 응답).

• list_sheets: 스프레드시트 내의 모든 시트/탭 이름을 나열합니다.

  • spreadsheet_id (문자열): 스프레드시트 ID (URL에서 가져옴).

  • 반환값: 시트/탭 이름 문자열 목록. 예: ["Sheet1", "Sheet2"].

• create_sheet: 스프레드시트에 새 시트/탭을 추가합니다.

  • spreadsheet_id (문자열): 스프레드시트 ID (URL에서 가져옴).

  • title (문자열): 새 시트/탭의 이름.

  • 반환값: 새 시트 속성 객체.

• get_multiple_sheet_data: 한 번의 호출로 잠재적으로 다른 여러 스프레드시트의 여러 범위에서 데이터를 가져옵니다.

  • queries (객체 배열): 각 객체에는 spreadsheet_id, sheet, range가 필요합니다. 예: [{"spreadsheet_id": "abc", "sheet": "Sheet1", "range": "A1:B2"}, ...].

  • 반환값: 각각 쿼리 매개변수와 가져온 data 또는 error를 포함하는 객체 목록. 각 data는 values.get 응답입니다.

• get_multiple_spreadsheet_summary: 여러 스프레드시트의 제목, 시트/탭 이름, 헤더 및 처음 몇 행을 가져옵니다.

  • spreadsheet_ids (문자열 배열): 스프레드시트의 ID (URL에서 가져옴).

  • rows_to_fetch (선택적 정수, 기본값 5): 미리 볼 행 수(헤더 포함). 예: 5.

  • 반환값: 각 스프레드시트에 대한 요약 객체 목록.

• share_spreadsheet: 지정된 사용자/이메일 및 역할과 스프레드시트를 공유합니다.

  • spreadsheet_id (문자열): 스프레드시트 ID (URL에서 가져옴).

  • recipients (객체 배열): [{"email_address": "user@example.com", "role": "writer"}, ...]. 역할: reader, commenter, writer.

  • send_notification (선택적 부울, 기본값 True): 수신자에게 이메일 알림을 보냅니다.

  • 반환값: successes 및 failures 목록이 있는 사전.

• add_columns: 지정된 인덱스에 시트/탭에 빈 열을 추가(삽입)합니다.

  • spreadsheet_id (문자열): 스프레드시트 ID (URL에서 가져옴).

  • sheet (문자열): 시트/탭 이름 (예: "Sheet1").

  • count (정수): 삽입할 빈 열 수.

  • start_column (선택적 정수, 기본값 0): 삽입을 시작할 0 기반 열 인덱스. 생략하면 0(시작 부분에 삽입)으로 기본 설정됩니다.

  • 반환값: 작업 결과 (batchUpdate 응답).

• copy_sheet: 한 스프레드시트에서 다른 스프레드시트로 시트/탭을 복제하고 선택적으로 이름을 바꿉니다.

  • src_spreadsheet (문자열): 원본 스프레드시트 ID (URL에서 가져옴).

  • src_sheet (문자열): 원본 시트/탭 이름 (예: "Sheet1").

  • dst_spreadsheet (문자열): 대상 스프레드시트 ID (URL에서 가져옴).

  • dst_sheet (문자열): 대상 스프레드시트에서 원하는 시트/탭 이름.

  • 반환값: 복사 및 선택적 이름 변경 작업의 결과.

• rename_sheet: 기존 시트/탭의 이름을 바꿉니다.

  • spreadsheet (문자열): 스프레드시트 ID (URL에서 가져옴).

  • sheet (문자열): 현재 시트/탭 이름 (예: "Sheet1").

  • new_name (문자열): 새 시트/탭 이름 (예: "Transactions").

  • 반환값: 작업 결과 (batchUpdate 응답).

• add_chart: 지정된 데이터로 Google 스프레드시트에 차트를 생성합니다.

  • spreadsheet_id (문자열): 스프레드시트 ID (URL에서 가져옴).

  • sheet (문자열): 데이터가 포함된 시트/탭 이름 (예: "Sheet1").

  • chart_type (문자열): 생성할 차트 유형. 옵션: COLUMN(세로 막대), BAR(가로 막대), LINE, AREA, PIE, SCATTER, COMBO, HISTOGRAM.

  • data_range (문자열): 차트 데이터의 A1 표기법 범위 (예: "A1:C10"). 첫 번째 행은 헤더로 처리됩니다.

  • title (선택적 문자열): 차트 제목.

  • x_axis_label (선택적 문자열): X축(하단 축)의 레이블. 파이 차트에는 적용되지 않습니다.

  • y_axis_label (선택적 문자열): Y축(왼쪽 축)의 레이블. 파이 차트에는 적용되지 않습니다.

  • position_x (선택적 정수, 기본값 0): 왼쪽 위 모서리에서 픽셀 단위의 가로 위치 오프셋.

  • position_y (선택적 정수, 기본값 0): 왼쪽 위 모서리에서 픽셀 단위의 세로 위치 오프셋.

  • width (선택적 정수, 기본값 600): 픽셀 단위의 차트 너비.

  • height (선택적 정수, 기본값 400): 픽셀 단위의 차트 높이.

  • 반환값: 성공 상태, 차트 ID 및 작업 세부 정보가 포함된 결과 객체.

MCP 리소스:

• spreadsheet://{spreadsheet_id}/info: Google 스프레드시트에 대한 기본 메타데이터를 가져옵니다.

  • 반환값: 스프레드시트 정보가 포함된 JSON 문자열.

☁️ Google Cloud Platform 설정 (상세)

이 설정은 서버를 실행하기 전에 필수입니다.

1. GCP 프로젝트 생성/선택: Google Cloud Console로 이동합니다.

2. API 활성화: "API 및 서비스" -> "라이브러리"로 이동합니다. 다음을 검색하여 활성화합니다:

   • Google Sheets API

   • Google Drive API

3. 자격 증명 구성: 아래 인증 방법 중 하나를 선택해야 합니다(서비스 계정 권장).

🔑 인증 및 환경 변수 (상세)

서버는 Google API에 접근하기 위해 자격 증명이 필요합니다. 한 가지 방법을 선택하세요:

아래 사용된 ID에 대한 자세한 내용은 ID 참조 가이드를 참조하세요.

방법 A: 서비스 계정 (서버/자동화에 권장) ✅

• 이유? 헤드리스(브라우저 불필요), 안전, 서버 환경에 이상적. 쉽게 만료되지 않음.

• 단계:

  1. 서비스 계정 생성: GCP 콘솔 -> "IAM 및 관리" -> "서비스 계정".

     • "+ 서비스 계정 만들기"를 클릭합니다. 이름을 지정합니다(예: mcp-sheets-service).

     • 역할 부여: 광범위한 접근을 위해 편집자 역할을 추가하거나, 더 세부적인 역할(예: roles/drive.file 및 특정 Sheets 역할)로 더 엄격한 권한을 설정합니다.

     • "완료"를 클릭합니다. 계정을 찾아 작업(⋮) -> "키 관리"를 클릭합니다.

     • "키 추가" -> "새 키 만들기" -> JSON -> "만들기"를 클릭합니다.

     • JSON 키 파일을 다운로드하여 안전하게 보관합니다.

  2. Google Drive 폴더 생성 및 공유:

     • Google Drive에서 폴더를 생성합니다(예: "AI Managed Sheets").

     • URL에서 폴더 ID를 확인합니다: https://drive.google.com/drive/folders/THIS_IS_THE_FOLDER_ID.

     • 폴더를 마우스 오른쪽 버튼으로 클릭 -> "공유" -> "공유"를 클릭합니다.

     • 서비스 계정의 이메일(JSON 파일의 client_email)을 입력합니다.

     • 편집자 액세스 권한을 부여합니다. "사람들에게 알림"을 선택 해제합니다. "공유"를 클릭합니다.

  3. 환경 변수 설정:

     • SERVICE_ACCOUNT_PATH: 다운로드한 JSON 키 파일의 전체 경로.

     • DRIVE_FOLDER_ID: 공유된 Google Drive 폴더의 ID. (OS별 예시는 초고속 시작을 참조하세요)

방법 B: OAuth 2.0 (대화형 / 개인용) 🧑💻

• 이유? 대화형 브라우저 로그인이 괜찮은 개인용 또는 로컬 개발용.

• 단계:

  1. OAuth 동의 화면 구성: GCP 콘솔 -> "API 및 서비스" -> "OAuth 동의 화면". "외부"를 선택하고 필수 정보를 입력하고 범위(.../auth/spreadsheets, .../auth/drive)를 추가하고 필요한 경우 테스트 사용자를 추가합니다.

  2. OAuth 클라이언트 ID 생성: GCP 콘솔 -> "API 및 서비스" -> "사용자 인증 정보". "+ 사용자 인증 정보 만들기" -> "OAuth 클라이언트 ID" -> 유형: 데스크톱 앱. 이름을 지정합니다. "만들기". JSON 다운로드.

  3. 환경 변수 설정:

     • CREDENTIALS_PATH: 다운로드한 OAuth 자격 증명 JSON 파일의 경로(기본값: credentials.json).

     • TOKEN_PATH: 첫 로그인 후 사용자의 새로 고침 토큰을 저장할 경로(기본값: token.json). 쓰기 가능해야 합니다.

방법 C: 직접 자격 증명 주입 (고급) 🔒

• 이유? Docker, Kubernetes, CI/CD와 같이 파일 관리가 어렵지만 환경 변수가 쉽고 안전한 환경에서 유용합니다. 파일 시스템 접근을 피할 수 있습니다.

• 방법? 자격 증명 파일의 경로를 제공하는 대신, 파일의 내용을 Base64로 인코딩하여 환경 변수에 직접 제공합니다.

• 단계:

  1. 자격 증명 JSON 파일을 가져옵니다 (서비스 계정 키 또는 OAuth 클라이언트 ID 파일). 이름을 your_credentials.json이라고 하겠습니다.

  2. Base64 문자열을 생성합니다:

     • (Linux/macOS): base64 -w 0 your_credentials.json

     • (Windows PowerShell):

       $filePath = "C:\path\to\your_credentials.json"; # Use actual path
       $bytes = [System.IO.File]::ReadAllBytes($filePath);
       $base64 = [System.Convert]::ToBase64String($bytes);
       $base64 # Copy this output

     • (주의): 신뢰할 수 없는 온라인 인코더에 민감한 자격 증명을 붙여넣지 마세요.

  3. 환경 변수를 설정합니다:

     • CREDENTIALS_CONFIG: 이 변수를 방금 생성한 전체 Base64 문자열로 설정합니다.

       # Example (Linux/macOS) - Use the actual string generated
       export CREDENTIALS_CONFIG="ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb..."

방법 D: 애플리케이션 기본 자격 증명 (ADC) 🌐

• 이유? Google Cloud 환경(GKE, Compute Engine, Cloud Run) 및 gcloud auth application-default login을 사용한 로컬 개발에 이상적입니다. 명시적인 자격 증명 파일이 필요 없습니다.

• 방법? Google의 애플리케이션 기본 자격 증명 체인을 사용하여 여러 소스에서 자격 증명을 자동으로 검색합니다.

• ADC 검색 순서:

  1. GOOGLE_APPLICATION_CREDENTIALS 환경 변수(서비스 계정 키 경로) - Google의 표준 변수

  2. gcloud auth application-default login 자격 증명(로컬 개발)

  3. 메타데이터 서버에서 연결된 서비스 계정(GKE, Compute Engine 등)

• 설정:

  • 로컬 개발:

    1. gcloud auth application-default login --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/drive를 한 번 실행합니다.

    2. 할당량 프로젝트를 설정합니다: gcloud auth application-default set-quota-project <project_id> (<project_id>를 Google Cloud 프로젝트 ID로 바꿉니다)

  • Google Cloud: 컴퓨팅 리소스에 서비스 계정을 연결합니다.

  • 환경 변수: GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json을 설정합니다 (Google의 표준)

• 추가 환경 변수 불필요 - 다른 방법이 실패하면 ADC가 자동으로 대체 수단으로 사용됩니다.

참고: GOOGLE_APPLICATION_CREDENTIALS는 Google의 공식 표준 환경 변수이고, SERVICE_ACCOUNT_PATH는 이 MCP 서버에 특화된 변수입니다. GOOGLE_APPLICATION_CREDENTIALS를 설정하면 ADC가 자동으로 이를 찾습니다.

인증 우선순위 및 요약

서버는 다음 순서로 자격 증명을 확인합니다:

1. CREDENTIALS_CONFIG (Base64 내용)

2. SERVICE_ACCOUNT_PATH (서비스 계정 JSON 경로)

3. CREDENTIALS_PATH (OAuth JSON 경로) - 토큰이 없거나 만료된 경우 대화형 흐름을 트리거합니다

4. 애플리케이션 기본 자격 증명 (ADC) - 자동 대체 수단

환경 변수 요약:

⚙️ 서버 실행 (상세)

아래에서 사용되는 ID에 대한 자세한 내용은 ID 참조 가이드를 참조하세요.

방법 1: uvx 사용 (사용자에게 권장)

초고속 시작에서 설명한 대로, 이것이 가장 쉬운 방법입니다. 환경 변수를 설정한 후 실행합니다:

uvx mcp-google-sheets@latest

uvx가 패키지를 임시로 가져와 실행합니다.

방법 2: 개발용 (리포지토리 클론)

코드를 수정하려는 경우:

1. 클론: git clone https://github.com/yourusername/mcp-google-sheets.git && cd mcp-google-sheets (실제 URL 사용)

2. 환경 변수 설정: 위에서 설명한 대로.

3. uv로 실행: (로컬 코드 사용)

   uv run mcp-google-sheets
   # Or via the script name if defined in pyproject.toml, e.g.:
   # uv run start

방법 3: Docker (SSE 전송)

포함된 Dockerfile을 사용하여 컨테이너에서 서버를 실행합니다:

# Build the image
docker build -t mcp-google-sheets .

# Run (SSE on port 8000)
# NOTE: Prefer CREDENTIALS_CONFIG (Base64 credentials content) in containers.
docker run --rm -p 8000:8000 ^
  -e HOST=0.0.0.0 ^
  -e PORT=8000 ^
  -e CREDENTIALS_CONFIG=YOUR_BASE64_CREDENTIALS ^
  -e DRIVE_FOLDER_ID=YOUR_DRIVE_FOLDER_ID ^
  mcp-google-sheets

• Docker 내부에서는 비밀을 파일로 마운트하지 않도록 SERVICE_ACCOUNT_PATH 대신 CREDENTIALS_CONFIG를 사용하세요.

• 컨테이너는 --transport sse로 시작하고 HOST/PORT에서 수신 대기합니다. SSE 전송을 사용하여 MCP 클라이언트를 http://localhost:8000으로 연결하세요.

🔌 Claude Desktop과 함께 사용하기

mcpServers 아래의 claude_desktop_config.json에 서버 구성을 추가합니다. 설정에 맞는 블록을 선택하세요:

아래에서 사용되는 ID에 대한 자세한 내용은 ID 참조 가이드를 참조하세요.

⚠️ 중요 참고 사항:

• 🍎 macOS 사용자: "uvx" 대신 전체 경로를 사용하세요: "/Users/yourusername/.local/bin/uvx"

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

🍎 macOS 참고: spawn uvx ENOENT 오류가 발생하면 uvx의 전체 경로를 사용하세요:

{
  "mcpServers": {
    "google-sheets": {
      "command": "/Users/yourusername/.local/bin/uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

yourusername을 실제 사용자 이름으로 바꾸세요.

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "CREDENTIALS_PATH": "/full/path/to/your/credentials.json",
        "TOKEN_PATH": "/full/path/to/your/token.json"
      }
    }
  }
}

참고: 처음 사용 시 Google 로그인을 위해 브라우저가 열릴 수 있습니다. TOKEN_PATH가 쓰기 가능한지 확인하세요.

🍎 macOS 참고: spawn uvx ENOENT 오류가 발생하면 "command": "uvx"를 "command": "/Users/yourusername/.local/bin/uvx"로 바꾸세요 (yourusername을 실제 사용자 이름으로 바꿉니다).

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "CREDENTIALS_CONFIG": "ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAi...",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

참고: CREDENTIALS_CONFIG에 전체 Base64 문자열을 붙여넣으세요. 서비스 계정 폴더 컨텍스트에는 DRIVE_FOLDER_ID가 여전히 필요합니다.

🍎 macOS 참고: spawn uvx ENOENT 오류가 발생하면 "command": "uvx"를 "command": "/Users/yourusername/.local/bin/uvx"로 바꾸세요 (yourusername을 실제 사용자 이름으로 바꿉니다).

옵션 1: GOOGLE_APPLICATION_CREDENTIALS 사용

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
      }
    }
  }
}

옵션 2: gcloud auth 사용 (환경 변수 불필요)

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {}
    }
  }
}

전제 조건:

1. 먼저 gcloud auth application-default login --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/drive를 실행하세요.

2. 할당량 프로젝트를 설정하세요: gcloud auth application-default set-quota-project <project_id>

🍎 macOS 참고: spawn uvx ENOENT 오류가 발생하면 "command": "uvx"를 "command": "/Users/yourusername/.local/bin/uvx"로 바꾸세요 (yourusername을 실제 사용자 이름으로 바꿉니다).

{
  "mcpServers": {
    "mcp-google-sheets-local": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/mcp-google-sheets",
        "mcp-google-sheets"
      ],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/path/to/your/mcp-google-sheets/service_account.json",
        "DRIVE_FOLDER_ID": "your_drive_folder_id_here"
      }
    }
  }
}

참고: --directory 플래그를 사용하여 프로젝트 경로를 지정하고, 경로를 실제 작업 공간 위치에 맞게 조정하세요.

💬 Claude용 예시 프롬프트

연결이 완료되면 다음과 같은 프롬프트를 시도해 보세요:

• "내가 액세스할 수 있는 모든 스프레드시트를 나열해 줘." (또는 "내 AI 관리 시트 폴더에서")

• "'2024년 3분기 판매 보고서'라는 제목의 새 스프레드시트를 만들어 줘."

• "'분기별 판매 보고서' 스프레드시트에서 Sheet1의 A1~E10 범위 데이터를 가져와 줘."

• "ID가 1aBcDeFgHiJkLmNoPqRsTuVwXyZ인 스프레드시트에 '요약'이라는 새 시트를 추가해 줘."

• "'프로젝트 작업' 스프레드시트의 '작업' 시트에서 B2 셀을 '진행 중'으로 업데이트해 줘."

• "스프레드시트 XYZ의 '로그' 시트에 다음 행을 추가해 줘: [['2024-07-31', '작업 A 완료'], ['2024-08-01', '작업 B 시작']]"

• "'판매 데이터'와 '재고 수량' 스프레드시트의 요약을 가져와 줘."

• "'팀 휴가 일정' 스프레드시트를 team@example.com과 읽기 권한으로, manager@example.com과 쓰기 권한으로 공유해 줘. 알림은 보내지 마."

• "'판매 보고서' 스프레드시트에 A1:B13 범위의 데이터로 월별 수익을 보여주는 세로 막대형 차트를 만들어 줘."

• "'시장 분석' 시트에 A1:B5 데이터로 '제품별 시장 점유율'이라는 제목의 원형 차트를 추가해 줘."

• "스프레드시트 abc123에서 Sheet1의 A1:C10 범위로 '성장 추세'라는 제목과 '월' 및 '수익' 레이블이 있는 꺾은선형 차트를 만들어 줘."

🆔 ID 참조 가이드

문서 전체에서 참조되는 다양한 ID를 찾으려면 다음 참조 가이드를 사용하세요:

Google Cloud Project ID:
  https://console.cloud.google.com/apis/dashboard?project=sheets-mcp-server-123456
                                                          └───── Project ID ─────┘

Google Drive Folder ID:
  https://drive.google.com/drive/u/0/folders/1xcRQCU9xrNVBPTeNzHqx4hrG7yR91WIa
                                             └────────── Folder ID ──────────┘

Google Sheets Spreadsheet ID:
  https://docs.google.com/spreadsheets/d/25_-_raTaKjaVxu9nJzA7-FCrNhnkd3cXC54BPAOXemI/edit
                                         └───────────── Spreadsheet ID ─────────────┘

🤝 기여하기

기여는 환영합니다! 버그나 기능 요청을 논의하려면 이슈를 열어 주세요. 풀 리퀘스트도 감사히 받습니다.

📄 라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.

🙏 크레딧

• FastMCP로 구축되었습니다.

• kazz187/mcp-google-spreadsheet에서 영감을 받았습니다.

• Google API Python 클라이언트 라이브러리를 사용합니다.