hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Integrations
Allows managing Gmail inbox, drafting emails, sorting newsletters, setting up labels and filters, handling attachments, and tracking responses to threads
Integrates with Google Workspace, providing access to Gmail, Calendar, and Drive within a unified interface through authenticated API access
Enables calendar management including scheduling meetings, managing recurring events, finding available time slots, and handling timezone conflicts
Google Workspace MCP 서버
이 모델 컨텍스트 프로토콜(MCP) 서버를 통해 Google Workspace를 제어할 수 있습니다. 계정을 연결하면(1분밖에 걸리지 않는 간단하고 안전한 과정) 바로 사용할 수 있습니다. 이 서버는 사용자의 연결을 안전하게 유지하고 활성 상태로 유지하므로 로그인 및 권한 관리에 시간을 허비하지 않고 업무에 집중할 수 있습니다.
Gmail 받은편지함을 상상도 못 했던 방식으로 관리해 보세요. 지난 분기에 제출했던 제안서를 찾고 계신가요? 몇 초 만에 찾을 수 있습니다. 뉴스레터에 푹 빠져 계신가요? 자동으로 폴더로 분류됩니다. 중요한 대화에 대한 답글을 추적해야 하나요? 라벨과 필터가 알아서 처리해 줍니다. 완벽한 이메일 초안 작성부터 팀과의 대화 관리까지, 모든 것이 제자리에 딱 들어맞습니다. 간소화된 첨부 파일 처리 기능을 통해 이메일 첨부 파일을 쉽게 찾고 관리할 수 있으며, 시스템에서 복잡한 메타데이터는 모두 자동으로 처리됩니다.
캘린더는 매일매일 바쁜 일정 속에서 든든한 동반자가 되어 줍니다. 더 이상 이중으로 예약된 회의나 시간대 혼란은 없습니다. 팀 동기화를 계획하고 계신가요? 캘린더가 최적의 시간을 찾아줍니다. 정기 워크숍을 진행하시나요? 한 번 설정하면 끝입니다. 계획이 변경되더라도 모두에게 맞는 새로운 시간을 쉽고 빠르게 찾을 수 있습니다. "언제 시간 되세요?"라는 이메일을 끊임없이 주고받는 시대는 이제 끝났습니다.
Google Drive를 파일 저장소에서 디지털 관리 센터로 전환하세요. 모든 문서는 제자리에 있고, 모든 폴더는 이야기를 담고 있습니다. 필요한 사람들과 파일을 공유하세요. 더 이상 "누가 이 파일을 수정할 수 있나요?"라는 혼란은 없습니다. 지난주 회의에서 발표했던 프레젠테이션을 찾고 계신가요? 파일 이름뿐 아니라 파일 내용까지 검색해 보세요. 작은 프로젝트를 진행하든, 산더미 같은 문서를 관리하든, 모든 것이 필요한 곳에 바로 보관됩니다.
TL;DR 설정
참고 : Cline과 같은 AI 어시스턴트의 경우, 전문 설치 지침은 llms-install.md를 참조하세요.
- Google Cloud 프로젝트 만들기:지엑스피1
- Cline 설정에 추가(예:
~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):로깅 모드:Copynormal(기본값): 각 로그 수준에 적합한 콘솔 방법을 사용합니다.strict: 모든 비 JSON-RPC 메시지를 stderr로 라우팅합니다(Claude 데스크톱에 권장)
- 클라인/클로드 재시작
- AI에게 "Google 계정을 추가해 줘"라고 말하기만 하면 됩니다. AI가 대화형으로 인증 과정을 안내해 줄 것입니다.
자세한 내용은 자세한 설정 가이드를 참조하세요.
필수 조건
이 MCP 서버를 사용하기 전에 Google Workspace API에 액세스할 수 있는 Google Cloud Project를 직접 설정해야 합니다.
- Google Cloud Console 에서 새 프로젝트를 만듭니다.
- 필요한 API를 활성화하세요:
- Gmail API
- 구글 캘린더 API
- 구글 드라이브 API
- OAuth 동의 화면을 구성하세요.
- "외부"로 설정
- 자신을 테스트 사용자로 추가하세요
- Gmail, 캘린더 및 드라이브에 필요한 범위 추가
- OAuth 2.0 자격 증명을 만듭니다.
- "데스크톱 응용 프로그램" 유형을 선택하세요
- 클라이언트 ID와 클라이언트 비밀번호를 기록해 두세요.
- 리디렉션 URI로 "urn:ietf:wg:oauth:2.0:oob"를 사용합니다(이렇게 하면 대역 외 인증이 가능해집니다).
MCP 서버에는 다음이 필요합니다.
- 위 단계의 Google OAuth 클라이언트 ID 및 비밀번호
- 구성을 저장하기 위한 로컬 디렉토리 경로(권장:
~/.mcp/google-workspace-mcp)
참고: 이 서버는 OOB(Out-of-band) 인증 흐름을 사용하므로 각 계정을 처음 설정할 때 승인 코드를 수동으로 복사하여 붙여넣어야 합니다.
Cline과 함께 사용
Cline MCP 설정에 다음 구성을 추가하세요.
파일 관리
서버는 구조화된 방식으로 파일을 자동으로 관리합니다.
WorkspaceManager는 이 구조를 자동으로 생성하고 유지 관리합니다.
- 파일이 다운로드/업로드될 때 필요에 따라 디렉토리를 생성합니다.
- 사용자 이메일별로 파일을 정리합니다
- 임시 파일 정리를 처리합니다
- 적절한 권한을 유지합니다
WORKSPACE_BASE_PATH 환경 변수를 설정하여 작업 공간 위치를 사용자 지정할 수 있습니다.
수동 사용
중요 : 서버에는 마운트된 config 디렉터리에
accounts.json파일이 필요합니다. 처음 설정하는 경우, 컨테이너를 시작하기 전에accounts.example.jsonconfig 디렉터리의accounts.json파일로 복사하세요.
컨테이너를 직접 실행할 수 있습니다.
서버는 자동으로 다음을 수행합니다.
- 필요한 모든 구성 파일을 생성하고 관리합니다.
- 자격 증명 및 토큰의 안전한 저장을 처리합니다.
- 적절한 파일 권한 유지
개발 빌드
로컬 빌드 스크립트
빠르고 CI와 유사한 로컬 빌드 및 Docker 이미지를 생성하려면 제공된 스크립트를 사용하세요.
- 기본적으로 이미지는
google-workspace-mcp:local로 태그됩니다. - 자세한 출력(모든 로그를 콘솔에 출력)을 사용하려면
--verbose추가하세요.Copy - Docker 이미지 태그를 변경하려면:Copy
- 로그 파일은 검토를 위해
/tmp/google-workspace-mcp/에 기록됩니다.
빌드 스크립트는 플랫폼별 설정이나 BuildKit 기능 없이 로컬 개발에 최적화된 Dockerfile.local 사용합니다. 이를 통해 다양한 개발 환경 간의 호환성이 보장됩니다.
수동 Docker 빌드
컨테이너를 수동으로 빌드하고 실행할 수도 있습니다.
특징
- 자동 메타데이터 관리를 통한 간소화된 첨부 파일 처리
- 필수 정보에 초점을 맞춘 간소화된 이메일 응답
- 강력한 첨부 파일 인덱싱 및 검색 시스템
- Gmail과 캘린더에서 효율적인 파일 관리
- 만료된 첨부 파일의 자동 정리
사용 가능한 도구
계정 관리
list_workspace_accounts(별칭: list_accounts, get_accounts, show_accounts)- 구성된 모든 Google 계정 및 인증 상태를 나열합니다.
- 다른 작업 전에 먼저 호출해야 합니다.
- 필요한 API 범위를 검증합니다.
- 여러 계정 선택을 처리합니다
authenticate_workspace_account(별칭: auth_account, add_account, connect_account)- API 액세스를 위해 Google 계정을 추가하고 인증합니다.
- 계정 분류(업무, 개인) 지원
- 사용자 상호 작용을 통한 OAuth 흐름 처리
- 토큰 새로 고침을 자동으로 관리합니다.
remove_workspace_account(별칭: delete_account, disconnect_account, remove_account)- Google 계정 및 관련 토큰 제거
- 저장된 자격 증명 정리
Gmail 운영
메시지 및 검색
search_workspace_emails(별칭: 검색_이메일, 찾기_이메일, 쿼리_이메일)- 고급 이메일 필터링 기능:
- 발신자/수신자 필터링
- 주제 및 내용 검색
- 날짜 범위 필터링
- 애착 존재
- 레이블 기반 필터링
- 복잡한 Gmail 쿼리 구문 지원
- 일반적인 검색 패턴:
- 회의 이메일
- HR/관리 커뮤니케이션
- 팀 업데이트
- 뉴스레터
- 고급 이메일 필터링 기능:
send_workspace_email(별칭: send_email, send_mail, create_email)- 전체 서식을 사용하여 이메일 보내기
- CC/BCC 수신자 지원
- 첨부 파일 처리
- 이메일 스레딩 지원
설정 및 구성
get_workspace_gmail_settings(별칭: get_gmail_settings, gmail_settings, get_mail_settings)- 계정 설정에 액세스
- 언어 기본 설정
- 서명 구성
- 휴가 응답자 상태
- 필터 및 전달 규칙
초안 관리
manage_workspace_draft(별칭: manage_draft, draft_operation, handle_draft)- CRUD 작업 초안 완료:
- 새로운 초안 만들기
- 기존 초안 읽기
- 초안 콘텐츠 업데이트
- 초안 삭제
- 초안 보내기
- 지원 대상:
- 새로운 이메일 초안
- 스레딩으로 초안 답글 작성
- 초안 수정
- 초안 보내기
- CRUD 작업 초안 완료:
라벨 관리
manage_workspace_label(별칭: manage_label, label_operation, handle_label)- 전체 레이블 CRUD 작업
- 중첩된 레이블 지원
- 사용자 정의 색상 구성
- 가시성 설정
manage_workspace_label_assignment(별칭: assign_label, modify_message_labels, change_message_labels)- 메시지에 라벨 적용/제거
- 배치 라벨 수정
- 시스템 레이블 업데이트
manage_workspace_label_filter(별칭: manage_filter, handle_filter, filter_operation)- 라벨 필터 생성 및 관리
- 복잡한 필터링 기준:
- 발신자/수신자 패턴
- 주제/내용 일치
- 애착 존재
- 메시지 크기 규칙
- 자동화된 작업:
- 라벨 적용
- 중요도 표시
- 상태 읽기
- 보관
캘린더 작업
이벤트 관리
list_workspace_calendar_events(별칭: list_events, get_events, show_events)- 필터링을 사용하여 캘린더 이벤트 나열
- 날짜 범위 지정
- 이벤트 내 텍스트 검색
- 사용자 정의 가능한 결과 제한
get_workspace_calendar_event(별칭: get_event, view_event, show_event)- 자세한 이벤트 정보
- 참석자 상태
- 이벤트 설정
manage_workspace_calendar_event(별칭: manage_event, update_event, respond_to_event)- 이벤트 대응 관리:
- 초대 수락/거절
- 임시로 표시
- 새로운 시간을 제안하다
- 이벤트 시간 업데이트
- 댓글 지원
- 시간대 처리
- 이벤트 대응 관리:
create_workspace_calendar_event(별칭: create_event, new_event, schedule_event)- 새 캘린더 이벤트 만들기
- 지원 대상:
- 단일 이벤트
- 반복 이벤트(RRULE 형식)
- 여러 참석자
- 시간대 지정
- 이벤트 설명
- 충돌 검사
delete_workspace_calendar_event(별칭: delete_event, remove_event, cancel_event)- 캘린더 이벤트 삭제
- 참석자를 위한 알림 옵션
드라이브 운영
파일 관리
list_drive_files(별칭: list_files, get_files, show_files)- 선택적 필터링을 사용하여 파일 나열
- 폴더별 필터링
- 사용자 정의 쿼리 지원
- 정렬 및 페이지 매김
- 필드 선택
search_drive_files(별칭: 검색_파일, 찾기_파일, 쿼리_파일)- 파일 콘텐츠 전체에서 전체 텍스트 검색
- MIME 유형으로 필터링
- 폴더별 필터링
- 휴지통에 버린 파일 포함/제외
- 고급 쿼리 옵션
upload_drive_file(별칭: upload_file, create_file, add_file)- 새 파일 업로드
- 파일 메타데이터 설정
- 상위 폴더 지정
- 다양한 파일 유형 지원
download_drive_file(별칭: download_file, get_file_content, fetch_file)- 모든 파일 유형을 다운로드하세요
- Google Workspace 파일 내보내기
- 형식 변환 옵션
- 자동 MIME 유형 처리
delete_drive_file(별칭: delete_file, remove_file, trash_file)- 파일 및 폴더 삭제
- 드라이브에서 깔끔하게 제거
폴더 작업
create_drive_folder(별칭: create_folder, new_folder, add_folder)- 새 폴더 만들기
- 중첩된 폴더 지원
- 상위 폴더 사양
- 폴더 메타데이터
권한
update_drive_permissions(별칭: share_file, update_sharing, modify_permissions)- 공유 설정 업데이트
- 다양한 권한 유형:
- 사용자 권한
- 그룹 권한
- 도메인 공유
- 공공 접근
- 다양한 접근 역할:
- 소유자
- 조직자
- 파일 정리
- 작가
- 댓글 작성자
- 리더
- 공개 파일에 대한 검색 설정
자세한 사용법은 API 문서를 참조하세요.
곧 출시 예정
미래 서비스
- 관리자 SDK 지원
- 추가 Google 서비스
테스트 전략
단위 테스트 접근 방식
- 단순화된 모킹
- 예측 가능한 테스트를 위해 정적 모의 응답을 사용하세요
- 단위 테스트에서 복잡한 엔드투엔드 시뮬레이션을 피하세요
- 한 번에 한 가지 기능만 테스트하는 데 집중하세요
- 간단한 구현으로 외부 종속성(OAuth, 파일 시스템)을 모의합니다.
- 테스트 조직
- 기능별 그룹 테스트(예: 계정 작업, 파일 작업)
- 명확하고 설명적인 테스트 이름을 사용하세요
- 테스트를 집중하고 분리하세요
- 테스트 사이에 모의 및 모듈 재설정
- 모의 관리
- jest.resetModules()를 사용하여 깨끗한 상태를 보장합니다.
- 모의 변경 후 모듈 다시 요구
- 모의 함수 호출을 명시적으로 추적합니다.
- 함수 호출과 결과를 모두 확인하세요
- 파일 시스템 테스트
- 간단한 JSON 구조를 사용하세요
- 형식보다는 데이터 정확성에 집중하세요
- 테스트 오류 시나리오(파일 누락, 잘못된 JSON)
- 구현 세부 정보 없이 파일 작업 확인
- 토큰 처리
- 정적 응답을 사용한 모의 토큰 검증
- 성공 및 실패 시나리오를 별도로 테스트합니다.
- OAuth 복잡성 없이 토큰 작업 확인
- 계정 관리자의 토큰 처리 로직에 초점을 맞추세요
테스트 실행
모범 사례
- 입증
- MCP 설정에서 자격 증명을 안전하게 저장하세요
- 최소한으로 필요한 범위를 사용하세요
- 토큰 새로 고침을 올바르게 처리하세요
- 오류 처리
- 응답 상태 확인
- 인증 오류를 적절하게 처리하세요
- 적절한 재시도를 구현하세요
- 구성 및 보안
- 각 사용자는 자신의 Google Cloud 프로젝트를 유지 관리합니다.
- MCP 설정에서 OAuth 자격 증명 구성
- ~/.mcp/google-workspace-mcp에 보안 토큰 저장소
- 정기적인 토큰 회전
- 민감한 파일은 절대 git에 커밋하지 마세요
- 구성 디렉토리에 적절한 파일 권한을 사용하세요
- 지역 개발 설정
- MCP 설정에서 OAuth 자격 증명 구성
- ~/.mcp/google-workspace-mcp 디렉토리를 생성합니다.
- 민감한 토큰을 버전 제어에서 제외하세요
- 각 계정에 대한 인증 스크립트 실행
문제 해결
일반적인 설정 문제
- 구성이 누락되었습니다
- 오류: "GOOGLE_CLIENT_ID 환경 변수가 필요합니다"
- 해결 방법: MCP 설정 파일에서 OAuth 자격 증명을 구성합니다(자세한 내용은 docs/API.md 참조).
- 인증 오류
- 오류: "잘못된 OAuth 자격 증명"
- 해결책:
- Google Cloud 프로젝트가 올바르게 구성되었는지 확인하세요.
- OAuth 동의 화면에서 자신을 테스트 사용자로 추가했는지 확인하세요.
- Gmail API와 Google Calendar API가 모두 활성화되어 있는지 확인하세요.
- MCP 설정의 자격 증명이 OAuth 클라이언트 구성과 일치하는지 확인하세요.
- 토큰 문제
- 오류: "토큰 새로 고침에 실패했습니다"
- 해결 방법:
remove_workspace_account사용하여 계정을 제거하고 다시 인증하세요. - Google Cloud 프로젝트에 필요한 API 범위가 활성화되어 있는지 확인하세요.
- 디렉토리 구조
- 오류: "디렉토리를 찾을 수 없습니다"
- 해결 방법: ~/.mcp/google-workspace-mcp가 적절한 권한으로 존재하는지 확인하세요.
- Docker가 구성 디렉토리를 마운트할 수 있는 권한이 있는지 확인하세요.
추가 도움이 필요하면 오류 처리 설명서를 참조하세요.
특허
MIT 라이선스 - 자세한 내용은 라이선스 파일을 참조하세요.
This server cannot be installed
Gmail 운영과 계획된 캘린더 지원에 중점을 두고 Google Workspace API에 대한 인증된 액세스를 제공하며, 보안된 OAuth 인증과 자세한 오류 처리를 통한 다중 계정 관리 기능을 제공합니다.
- TL;DR Setup
- Prerequisites
- Features
- Available Tools
- Coming Soon
- Testing Strategy
- Best Practices
- Troubleshooting
- License