google-workspace-mcp

Gmail + Calendar + Drive + Docs + Sheets용 멀티 계정, 토큰 효율적 MCP. 공식 Claude 커넥터가 단일 계정만 지원하고 기본적으로 전체 메시지/파일 본문을 반환하기 때문에 만들어졌습니다.

왜 이게 필요한가

• 멀티 계정: 여러 사서함(업무 + 개인 + 공동 창업자)을 OAuth로 인증합니다. 모든 도구는 account 이메일을 받으며, 별칭은 Send-As ID로 처리됩니다.

• 토큰 효율적: 검색/목록은 간결한 형태({id, from, subject, snippet, ...} for mail, {id, name, mime, modified, size, ...} for Drive)를 반환합니다. 본문과 파일 내용은 선택 사항입니다.

• 키링 기반: 갱신 토큰은 OS 자격 증명 저장소(macOS의 Keychain, Windows의 Credential Manager, Linux의 Secret Service)에 저장되며, 평문 파일에 저장되지 않습니다. 볼트에 토큰 없음, 저장소에 토큰 없음.

• macOS, Windows, Linux: 플랫폼별 설치 프로그램 하나, 동일한 커넥터.

Related MCP server: google-workspace-mcp

도구 (v2, 63개 도구)

계정 관리 (3)

• gws_account_add — 브라우저 OAuth 흐름, 새 인증 사서함 추가

• gws_account_list — 인증된 계정 + 기본 계정 목록

• gws_account_remove — 로컬 자격 증명 제거(Google 측은 해지하지 않음)

Gmail (12)

• gmail_search — Gmail 연산자로 검색. 간결한 응답.

• gmail_read — 메시지 하나 또는 전체 스레드 읽기. 본문은 선택 사항.

• gmail_send — 메일 보내기, 선택적 from_alias로 Send-As ID 사용

• gmail_draft — 임시 보관함 만들기

• gmail_reply — 답장(스레드 + 헤더 유지), 선택적 reply_all

• gmail_labels_list — 모든 라벨 나열

• gmail_label_apply — 라벨 일괄 추가/제거

• gmail_archive — 일괄 보관(INBOX 제거)

• gmail_trash — 일괄 휴지통으로 이동

• gmail_sendas_list — 이 사서함의 Send-As ID 나열

• gmail_attachments_list — 메시지의 첨부 파일 나열(파일 이름, MIME 유형, 크기)

• gmail_attachment_save — 첨부 파일 하나를 로컬 파일로 다운로드, 직접 읽을 수 있는 경로 반환

캘린더 (7)

• cal_list_calendars — 모든 캘린더 나열

• cal_list_events — 예정된 이벤트 나열(기본적으로 간결, 전체는 verbose=True)

• cal_create_event — 이벤트 만들기, 선택적 Google Meet 링크

• cal_update_event — 필드 부분 업데이트

• cal_delete_event — 삭제

• cal_freebusy — 일정 잡기 위한 바쁜 시간 확인

• cal_respond — 수락/거절/잠정

Drive (18)

• drive_search — 자유 텍스트 또는 원시 Drive q-구문. 메타데이터 전용 응답.

• drive_read_file — 기본적으로 메타데이터, 본문은 include_content=True

• drive_list_folder — 폴더의 직접 하위 항목('root'는 내 드라이브)

• drive_create_folder — 선택적 상위 폴더 아래에 폴더 만들기

• drive_upload — 로컬 파일 업로드, 선택적 convert_to_google

• drive_move — 상위 폴더 변경

• drive_rename — 파일 또는 폴더 이름 바꾸기

• drive_share — 이메일로 읽기/댓글/쓰기 등 권한 부여

• drive_trash — 소프트 삭제(복구 가능)

• drive_untrash — 휴지통에서 복원

• drive_permission_list — 파일에 접근 권한이 있는 모든 사람 나열

• drive_permission_update — 수신자의 역할 변경

• drive_permission_delete — 권한 해지

• drive_shared_drives_list — 이 계정이 접근하는 공유 드라이브 나열

• drive_comments_list — 모든 Drive 파일(Doc/Sheet/Slide/업로드)의 댓글 나열

• drive_comment_add — 댓글 추가, 선택적 앵커

• drive_comment_reply — 댓글에 답글

• drive_comment_resolve — 댓글을 해결됨으로 표시

Docs (9)

• docs_create — 새 문서, 선택적 초기 본문 및 상위 폴더

• docs_read — 기본적으로 평문, 전체 Docs API 트리는 structured=True

• docs_append — 본문 끝에 텍스트 추가

• docs_insert_at — 특정 인덱스에 텍스트 삽입

• docs_replace_text — 찾기 및 바꾸기, 바뀐 횟수 반환

• docs_export — markdown / pdf / docx / rtf / plain으로 내보내기

• docs_suggestions_list — 대기 중인 변경 제안 나열

• docs_suggestions_accept_all — 모든 제안 수락(문서 다시 쓰기)

• docs_suggestions_reject_all — 모든 제안 거부(문서 다시 쓰기)

Sheets (14)

• sheets_create — 새 통합 문서, 선택적 상위 폴더

• sheets_list_sheets — 행/열 크기와 함께 탭 나열

• sheets_add_sheet — 기존 통합 문서에 새 탭 추가

• sheets_read_range — A1 범위 읽기. FORMULA / UNFORMATTED_VALUE 옵션.

• sheets_write_range — 범위 덮어쓰기. USER_ENTERED는 수식 구문 분석.

• sheets_append — 기존 데이터 아래에 행 추가

• sheets_clear_range — 값 지우기(서식 유지)

• sheets_batch_read — 한 번의 API 호출로 여러 범위 읽기

• sheets_batch_write — 한 번의 API 호출로 여러 범위 쓰기

• sheets_named_ranges_list — 통합 문서의 명명된 범위 나열

• sheets_named_range_add — 명명된 범위 만들기

• sheets_named_range_delete — 명명된 범위 삭제

• sheets_conditional_format_add — 조건부 서식 규칙 추가

• sheets_data_validation_add — 드롭다운 / 숫자 / 이메일 / URL 유효성 검사 설정

설치

가장 빠른 방법 — 스크립트 하나, 수동 연결 없음.

macOS 및 Linux:

git clone https://github.com/adelaidasofia/google-workspace-mcp.git
bash google-workspace-mcp/install.sh

Windows (PowerShell):

git clone https://github.com/adelaidasofia/google-workspace-mcp.git
powershell -ExecutionPolicy Bypass -File .\google-workspace-mcp\install.ps1

설치 프로그램은 격리된 venv를 만들고, 종속성을 설치하고, Google OAuth 클라이언트(대화식 또는 환경의 GWS_CLIENT_ID / GWS_CLIENT_SECRET 사용)를 받아서 Claude Code에 서버를 등록합니다. 다시 실행해도 안전합니다. 먼저 Google OAuth 클라이언트가 필요합니다 — SETUP.md에서 약 45분의 일회성 GCP 설정을 참조하세요. 그런 다음 Claude Code에서 gws_account_add를 실행하여 첫 번째 사서함을 인증하세요.

둘 다 Python 3.10 이상이 필요하며 이미 있는 Python을 찾습니다.

• macOS / Linux는 python3를 먼저 시도한 다음 python3.14부터 python3.10까지 시도하므로, python3가 macOS의 오래된 시스템 Python으로 해석되어도 Homebrew Python이 인정됩니다.

• Windows는 py -3(Python 런처)를 먼저 시도한 다음 python, python3 및 버전 이름을 시도합니다. 각 후보는 실행되어 자체 버전을 보고해야 인정되며, 이는 %LOCALAPPDATA%\Microsoft\WindowsApps의 Microsoft Store 자리 표시자가 선택되는 것을 방지합니다. 그것은 PATH에 있는 실제 python.exe로, Store만 엽니다.

검색이 추측할 수 없는 위치(예: pyenv, conda, 개인 접두사)에 있다면 이름을 지정하세요:

GWS_PYTHON=/full/path/to/python3 bash google-workspace-mcp/install.sh

$env:GWS_PYTHON = 'C:\full\path\to\python.exe'
powershell -ExecutionPolicy Bypass -File .\google-workspace-mcp\install.ps1

-ExecutionPolicy Bypass는 의도적으로 명령에 포함되어 있습니다. Windows는 기본적으로 다운로드된 스크립트를 차단합니다. 이는 이 한 번의 실행에 예외를 적용하며 시스템 정책을 변경하지 않습니다.

Git Bash가 아닌 PowerShell에서 실행하세요. install.sh는 Git Bash / MSYS를 감지하고 네이티브 Claude Code가 시작할 수 없는 POSIX venv 경로를 등록하는 대신 install.ps1을 가리키며 중지합니다. WSL은 실제 Linux이므로 계속 install.sh를 사용합니다.

시간대. 커넥터는 시스템의 IANA 영역을 읽어 cal_* 호출의 "오후 3시"가 현재 위치의 오후 3시를 의미하도록 합니다. Windows는 자체 방식으로 영역 이름을 지정하므로(SA Western Standard Time), 설치 프로그램이 가져오는 tzlocal을 통해 처리됩니다. GWS_TIME_ZONE=America/Bogota로 재정의할 수 있습니다.

Claude Code를 열고 다음을 붙여넣으세요:

/plugin marketplace add adelaidasofia/google-workspace-mcp
/plugin install google-workspace-mcp@google-workspace-mcp

서버가 OAuth할 client_secret.json을 가지려면 SETUP.md의 일회성 GCP 설정(v1은 약 45분, v2 Drive/Docs/Sheets는 약 5분 추가)을 완료해야 합니다. Claude Code에서 gws_account_add를 실행하여 첫 번째 사서함을 인증하세요.

Windows에서는 이후 install.ps1을 실행하세요. 플러그인의 .mcp.json은 python3로 서버를 시작하며, 플러그인 매니페스트는 "Windows에서는 이것 대신 사용"을 지정할 방법이 없습니다. Windows에서 python3는 없거나 Microsoft Store 자리 표시자이므로 커넥터가 등록되어도 시작되지 않습니다. install.ps1은 절대 인터프리터 경로로 다시 등록하므로 모든 플랫폼에서 명확합니다.

일회성 GCP 설정은 SETUP.md를 참조하세요(v1은 약 45분, v2에서 Drive/Docs/Sheets 활성화는 약 5분 추가).

설정 후:

pip3 install --break-system-packages -r requirements.txt

Claude Code에 등록

프로젝트의 .mcp.json(또는 전역 액세스의 경우 ~/.claude.json)에 추가하세요:

"google-workspace": {
  "type": "stdio",
  "command": "python3",
  "args": ["/path/to/google-workspace-mcp/server.py"]
}

Windows에서는 단순한 이름 대신 실제 인터프리터의 전체 경로를 지정하세요 — python3는 일반적으로 Microsoft Store 자리 표시자이며, 해석은 되지만 Python을 실행하지 않습니다:

"google-workspace": {
  "type": "stdio",
  "command": "C:\\Users\\you\\google-workspace-mcp\\.venv\\Scripts\\python.exe",
  "args": ["C:\\Users\\you\\google-workspace-mcp\\server.py"]
}

v1 → v2 업그레이드

v2는 Drive + Docs + Sheets 범위를 추가합니다. 각 인증된 계정은 한 번 다시 OAuth해야 Google이 새 범위를 부여합니다. SETUP.md 6b 단계를 참조하세요.

로드맵

• v3: Gmail 필터, 휴가 응답, 푸시 알림(Gmail Watch), Calendar ACL/위임, Slides, Forms, Tasks

• v4: 서비스 간 일괄 요청, Drive 개정

관련 MCP

동일한 작성자, 동일한 아키텍처 패턴(FastMCP, 쓰기 시 초안+확인, 볼트 자동 내보내기, MIT):

• slack-mcp — 멀티 워크스페이스 Slack

• imessage-mcp — macOS iMessage

• whatsapp-mcp — whatsmeow을 통한 WhatsApp

• apollo-mcp — Apollo.io CRM + 시퀀스

• substack-mcp — Substack 작성 + 분석

• luma-mcp — lu.ma 이벤트

• parse-mcp — markitdown / Docling / LlamaParse 라우터

• rescuetime-mcp — RescueTime 생산성 데이터

• graph-query-mcp — 볼트 지식 그래프 쿼리

• graph-autotagger-mcp — 그래프의 위키링크 제안

• investor-relations-mcp — 시드 라운드 파이프라인 추적기

• vault-sync-mcp — 양방향 볼트 동기화

텔레메트리

이 플러그인은 특정 머신의 Claude Code 세션에서 처음 로드될 때 myceliumai.co로 단일 익명 설치 신호를 보냅니다.

전송되는 것:

• 플러그인 이름(예: slack-mcp)

• 플러그인 버전(예: 0.1.0)

전송되지 않는 것:

• 사용자 식별자, 이름, 이메일, 토큰 또는 API 키 없음

• 파일 경로, 메시지 내용 또는 작업의 어떤 것도 없음

• 중복 제거 처리 후 IP 주소는 저장되지 않음

이유: 유지 관리자가 사람들이 실제로 설치하는 플러그인을 알 수 있도록 하여 사용되는 플러그인에 관심을 집중시키기 위함입니다.

옵트아웃: Claude Code를 실행하기 전에 환경 변수 MYCELIUM_NO_PING=1을 설정하세요. 훅은 네트워크 호출을 완전히 건너뜁니다. 이미 핑된 설치본은 ~/.mycelium/onboarded-<plugin>에 센티널을 남깁니다 — 상태를 초기화하려면 삭제하세요.

라이선스

MIT

Mycelium AI가 제작했습니다. 전체 설치 또는 팀 버전은 diazroa.com에서 확인하세요.