google-workspace-mcp

Gmail + Calendar + Drive + Docs + Sheets를 위한 다중 계정, 토큰 효율적인 MCP입니다. 공식 Claude 커넥터는 하나의 계정만 지원하고 기본적으로 전체 메시지/파일 본문을 반환하기 때문에 제작되었습니다.

왜 이 도구가 필요한가요?

• 다중 계정: 여러 메일함(업무용 + 개인용 + 공동 창업자용)을 OAuth로 연결합니다. 모든 도구는 account 이메일을 인자로 받으며, 별칭(alias)은 Send-As ID를 통해 처리됩니다.

• 토큰 효율성: 검색/목록 조회 시 컴팩트한 형태({id, from, subject, snippet, ...} (메일), {id, name, mime, modified, size, ...} (Drive))로 반환합니다. 본문과 파일 내용은 필요할 때만 선택적으로 가져옵니다.

• 키체인 기반: 새로 고침 토큰은 일반 텍스트 파일이 아닌 macOS 키체인에 저장됩니다. 볼트나 저장소에 토큰이 남지 않습니다.

도구 (v2, 61개 도구)

계정 관리 (3)

• gws_account_add — 브라우저 OAuth 흐름을 통해 새로운 인증된 메일함 추가

• gws_account_list — 인증된 계정 및 기본 계정 목록 조회

• gws_account_remove — 로컬 자격 증명 제거 (Google 측 권한은 취소되지 않음)

Gmail (10)

• gmail_search — Gmail 연산자를 사용한 검색. 컴팩트한 응답.

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

• gmail_send — 메일 발송, Send-As ID를 위한 선택적 from_alias 지원

• gmail_draft — 초안 작성

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

• gmail_labels_list — 모든 라벨 목록 조회

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

• gmail_archive — 일괄 보관 (받은 편지함에서 제거)

• gmail_trash — 일괄 휴지통 이동

• gmail_sendas_list — 해당 메일함의 Send-As ID 목록 조회

Calendar (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-syntax 검색. 메타데이터만 응답.

• 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 — 기본값은 평문 텍스트; structured=True 시 전체 Docs API 트리 반환

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

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

• docs_replace_text — 찾기 및 바꾸기, 교체된 횟수 반환

• docs_export — 마크다운 / PDF / docx / rtf / 일반 텍스트로 내보내기

• 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 유효성 검사 설정

설치

일회성 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"]
}

v1에서 v2로 업그레이드

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

로드맵

• v3: Gmail 필터, 부재중 응답, 푸시 알림(Gmail Watch), 캘린더 ACL/위임, Slides, Forms, Tasks

• v4: 서비스 간 일괄 요청, Drive 수정 내역

라이선스

MIT