mcp-google-sheets

🤔 이게 뭐예요?

mcp-google-sheets 는 Python 기반 MCP 서버로, Claude Desktop과 같은 MCP 호환 클라이언트와 Google 스프레드시트 API를 연결하는 다리 역할을 합니다. 정의된 도구 세트를 사용하여 Google 스프레드시트와 상호 작용할 수 있으며, AI 기반 강력한 자동화 및 데이터 조작 워크플로를 구현할 수 있습니다.

🚀 빠른 시작( uvx 사용)

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

이 cmd는 필요한 경우 최신 코드를 자동으로 다운로드하여 실행합니다. 하지만 Google Cloud를 설정하는 데는 꽤 많은 단계가 필요하므로 아래 단계를 참조하세요.

1. ☁️ 필수 조건: Google Cloud 설정
   • 먼저 Google Cloud Platform 사용자 인증 정보를 구성하고 필요한 API를 활성화 해야 합니다 . 서비스 계정을 사용하는 것을 적극 권장합니다.
   • ➡️ 아래의 자세한 Google Cloud Platform 설정 가이드로 이동하세요.
2. 🐍 uv 설치
   • uvx 빠른 Python 패키지 설치 및 확인 프로그램인 uv 의 일부입니다. 아직 설치하지 않았다면 지금 설치하세요.지엑스피1필요한 경우 설치 프로그램 출력의 지침에 따라 uv PATH에 추가하세요.
3. 🔑 필수 환경 변수 설정(서비스 계정 권장)
   • 서버에 인증 방법을 알려줘야 합니다. 터미널에서 다음 변수를 설정하세요.
   • (리눅스/맥OS)
     # 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"
   • (윈도우 CMD)
     set SERVICE_ACCOUNT_PATH="C:\path\to\your\service-account-key.json" set DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
   • (윈도우 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
   • 서버가 시작되고 준비가 되었음을 나타내는 로그가 인쇄됩니다.
5. 🔌 MCP 클라이언트 연결
   • 실행 중인 서버에 연결하도록 클라이언트(예: Claude Desktop)를 구성합니다.
   • 사용하는 클라이언트에 따라 4단계가 필요하지 않을 수도 있습니다. 클라이언트가 서버를 자동으로 실행해 주기 때문입니다. 하지만 4단계를 테스트하여 모든 것이 제대로 설정되었는지 확인하는 것이 좋습니다.
   • ➡️ 예시는 Claude Desktop에서의 사용법을 참조하세요.

준비되었습니다! MCP 클라이언트를 통해 명령을 실행해 보세요.

✨ 주요 특징

• 원활한 통합: Google Drive 및 Google Sheets API에 직접 연결됩니다.
• 포괄적인 도구: 다양한 작업(CRUD, 목록 작성, 일괄 처리, 공유, 서식 지정 등)을 제공합니다.
• 유연한 인증: 서비스 계정(권장) , OAuth 2.0 및 환경 변수를 통한 직접 자격 증명 주입을 지원합니다.
• 간편한 배포: uvx 사용하여 즉시 실행(설치가 필요 없음)하거나 uv 사용하여 개발용으로 복제하세요.
• AI 지원: MCP 호환 클라이언트와 함께 사용하도록 설계되어 자연어 스프레드시트 상호 작용이 가능합니다.

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

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

(입력 매개변수는 달리 지정하지 않는 한 일반적으로 문자열입니다)

• list_spreadsheets : 구성된 Drive 폴더(서비스 계정)에 있는 스프레드시트나 사용자가 액세스할 수 있는 스프레드시트(OAuth)를 나열합니다.
  • 반환: 객체 목록 [{id: string, title: string}]
• create_spreadsheet : 새로운 스프레드시트를 만듭니다.
  • title (문자열): 원하는 제목입니다.
  • 반환: 스프레드시트 정보가 있는 객체( spreadsheetId 포함)
• get_sheet_data : 시트의 범위에서 데이터를 읽습니다.
  • spreadsheet_id (문자열)
  • sheet (문자열): 시트의 이름입니다.
  • range (선택적 문자열): A1 표기법(예: 'A1:C10' , 'Sheet1!B2:D' ). 생략하면 전체 시트를 읽습니다.
  • 반환값: 셀 값의 2D 배열.
• update_cells : 특정 범위에 데이터를 쓰고, 기존 데이터를 덮어씁니다.
  • spreadsheet_id (문자열)
  • sheet (끈)
  • range (문자열): A1 표기법.
  • data (2차원 배열): 쓸 값입니다.
  • 반환: 결과 객체를 업데이트합니다.
• batch_update_cells : 하나의 API 호출로 여러 범위를 업데이트합니다.
  • spreadsheet_id (문자열)
  • sheet (끈)
  • ranges (객체): 범위 문자열(A1 표기법)을 값의 2차원 배열 { "A1:B2": [[1, 2], [3, 4]], "D5": [["Hello"]] } .
  • 반환: 일괄 업데이트 결과 객체.
• add_rows : 시트의 끝(데이터가 있는 마지막 행 뒤)에 행을 추가합니다.
  • spreadsheet_id (문자열)
  • sheet (끈)
  • data (2차원 배열): 추가할 행입니다.
  • 반환: 결과 객체를 업데이트합니다.
• list_sheets : 스프레드시트 내의 모든 시트 이름을 나열합니다.
  • spreadsheet_id (문자열)
  • 반환: 시트 이름 문자열 목록 ["Sheet1", "Sheet2"] .
• create_sheet : 스프레드시트에 새로운 시트(탭)를 추가합니다.
  • spreadsheet_id (문자열)
  • title (문자열): 새 시트의 이름입니다.
  • 반환: 새로운 시트 속성 객체.
• get_multiple_sheet_data : 한 번의 호출로 잠재적으로 서로 다른 스프레드시트의 여러 범위에서 데이터를 가져옵니다.
  • queries (객체 배열): 각 객체에는 spreadsheet_id , sheet , range 필요합니다. [{spreadsheet_id: 'abc', sheet: 'Sheet1', range: 'A1:B2'}, ...] .
  • 반환: 쿼리 매개변수와 가져온 data 또는 error 각각 포함하는 개체 목록입니다.
• get_multiple_spreadsheet_summary : 여러 스프레드시트의 제목, 시트 이름, 머리글 및 처음 몇 행을 가져옵니다.
  • spreadsheet_ids (문자열 배열)
  • rows_to_fetch (선택적 정수, 기본값 5): 미리 볼 행 수(헤더 포함).
  • 반환: 각 스프레드시트에 대한 요약 개체 목록입니다.
• share_spreadsheet : 지정된 사용자/이메일 및 역할과 스프레드시트를 공유합니다.
  • spreadsheet_id (문자열)
  • recipients (객체 배열): [{email_address: 'user@example.com', role: 'writer'}, ...] . 역할: reader , commenter , writer .
  • send_notification (선택적 부울, 기본값 True): 이메일 알림을 보냅니다.
  • 반환: successes 및 failures 목록이 있는 사전입니다.
• add_columns : 시트에 열을 추가합니다. (매개변수가 구현된 경우 확인)
• copy_sheet : 스프레드시트 내에서 시트를 복제합니다. (구현된 경우 매개변수 확인)
• rename_sheet : 기존 시트의 이름을 변경합니다. (구현된 경우 매개변수 확인)

MCP 리소스:

• spreadsheet://{spreadsheet_id}/info : Google 스프레드시트에 대한 기본 메타데이터를 가져옵니다.
  • 반환: 스프레드시트 정보가 포함된 JSON 문자열.

☁️ Google Cloud Platform 설정(자세히)

서버를 실행하기 전에 이 설정이 필요합니다 .

1. GCP 프로젝트 만들기/선택: Google Cloud Console 로 이동합니다.
2. API 활성화: "API 및 서비스" -> "라이브러리"로 이동합니다. 다음 API를 검색하여 활성화합니다.
   • Google Sheets API
   • Google Drive API
3. 자격 증명 구성: 아래에서 하나의 인증 방법을 선택해야 합니다(서비스 계정 권장).

🔑 인증 및 환경 변수(자세히)

Google API에 액세스하려면 서버에 사용자 인증 정보가 필요합니다. 다음 방법 중 하나를 선택하세요.

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

• 왜냐고요? 헤드리스(브라우저 필요 없음), 보안, 서버 환경에 적합하고, 쉽게 만료되지 않기 때문입니다.
• 단계:
  1. 서비스 계정 만들기: GCP 콘솔 -> "IAM 및 관리자" -> "서비스 계정".
     • "+ 서비스 계정 만들기"를 클릭하세요. 계정 이름을 지정하세요(예: mcp-sheets-service ).
     • 역할 부여: 광범위한 액세스 권한을 원할 경우 Editor 역할을 추가하고, 더 엄격한 권한을 원할 경우 더 세부적인 역할(예: roles/drive.file 및 특정 시트 역할)을 추가합니다.
     • "완료"를 클릭하세요. 계정을 찾은 후 작업(⋮) -> "키 관리"를 클릭하세요.
     • "키 추가" -> "새 키 만들기" -> JSON -> "만들기"를 클릭합니다.
     • JSON 키 파일을 다운로드하여 안전하게 저장하세요 .
  2. Google Drive 폴더 만들기 및 공유:
     • Google 드라이브 에서 폴더(예: "AI 관리 시트")를 만듭니다.
     • URL https://drive.google.com/drive/folders/THIS_IS_THE_FOLDER_ID 에서 폴더 ID를 확인하세요.
     • 폴더를 마우스 오른쪽 버튼으로 클릭 -> "공유" -> "공유".
     • 서비스 계정의 이메일을 입력합니다(JSON 파일 client_email ).
     • 편집자 권한을 부여하세요. "다른 사람에게 알림"을 선택 해제하세요. "공유"를 클릭하세요.
  3. 환경 변수 설정:
     • SERVICE_ACCOUNT_PATH : 다운로드한 JSON 키 파일의 전체 경로입니다.
     • DRIVE_FOLDER_ID : 공유 Google Drive 폴더의 ID입니다. (OS별 예시는 Ultra Quick Start를 참조하세요.)

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

• 왜 그럴까요? 개인적인 용도나 대화형 브라우저 로그인이 허용되는 로컬 개발 환경에서 사용하기 때문입니다.
• 단계:
  1. OAuth 동의 화면 구성: GCP 콘솔 -> "API 및 서비스" -> "OAuth 동의 화면"에서 "외부"를 선택하고 필수 정보를 입력한 후, 범위( .../auth/spreadsheets , .../auth/drive )를 추가하고, 필요한 경우 테스트 사용자를 추가합니다.
  2. OAuth 클라이언트 ID 생성: GCP 콘솔 -> "API 및 서비스" -> "사용자 인증 정보"에서 "+ CREATE CREDENTIALS" -> "OAuth 클라이언트 ID"를 선택하고, 데스크톱 앱을 입력한 후 "CREATE"라는 이름을 지정합니다. 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..."

인증 우선순위 및 요약

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

1. CREDENTIALS_CONFIG (Base64 콘텐츠)
2. SERVICE_ACCOUNT_PATH (서비스 계정 JSON 경로)
3. CREDENTIALS_PATH (OAuth JSON 경로) - 토큰이 없거나 만료된 경우 대화형 흐름을 트리거합니다.

환경 변수 요약:

⚙️ 서버 실행(자세히)

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

Ultra Quick Start 에서 볼 수 있듯이, 이것이 가장 쉬운 방법입니다. 환경 변수를 설정한 후 다음을 실행하세요.

uvx 패키지를 일시적으로 가져오고 실행합니다.

방법 2: 개발용(Repo 복제)

코드를 수정하려면 다음을 수행하세요.

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

🔌 Claude Desktop과 함께 사용

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

(처음 사용 시 Google 로그인을 위해 브라우저가 열릴 수 있습니다)

💬 클로드에 대한 예시 프롬프트

연결되면 다음과 같은 메시지를 시도해 보세요.

• "내가 액세스할 수 있는 모든 스프레드시트를 나열합니다."(또는 "내 AI 관리 시트 폴더")
• "'2024년 3분기 매출 보고서'라는 제목의 새 스프레드시트를 만드세요."
• '분기별 판매 보고서' 스프레드시트에서 시트 1의 범위 A1~E10에서 데이터를 가져옵니다.
• "스프레드시트에 '요약'이라는 이름의 새 시트를 ID 1aBcDeFgHiJkLmNoPqRsTuVwXyZ 로 추가합니다."
• '프로젝트 작업' 스프레드시트의 '작업' 시트에서 B2 셀을 '진행 중'으로 업데이트하세요.
• " XYZ 스프레드시트의 '로그' 시트에 다음 행을 추가합니다: [['2024-07-31', 'Task A Completed'], ['2024-08-01', 'Task B Started']] "
• "판매 데이터'와 '재고 수량' 스프레드시트의 요약을 받으세요."
• '팀 휴가 일정' 스프레드시트를 team@example.com 에게 독자 권한으로, manager@example.com 에게 작성 권한으로 공유하세요. 알림은 보내지 마세요.

🤝 기여하기

기여를 환영합니다! 버그나 기능 요청은 이슈를 통해 논의해 주세요. 풀 리퀘스트도 환영합니다.

📄 라이센스

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

🙏 크레딧

• FastMCP 로 구축됨.
• kazz187/mcp-google-spreadsheet 에서 영감을 얻었습니다.
• Google API Python 클라이언트 라이브러리를 사용합니다.