Google Workspace MCP 서버

이 모델 컨텍스트 프로토콜(MCP) 서버를 통해 Google Workspace를 제어할 수 있습니다. 계정을 연결하면(1분밖에 걸리지 않는 간단하고 안전한 과정) 바로 사용할 수 있습니다. 이 서버는 사용자의 연결을 안전하게 유지하고 활성 상태로 유지하므로 로그인 및 권한 관리에 시간을 허비하지 않고 업무에 집중할 수 있습니다.

Gmail 받은편지함을 상상도 못 했던 방식으로 관리해 보세요. 지난 분기에 제출했던 제안서를 찾고 계신가요? 몇 초 만에 찾을 수 있습니다. 뉴스레터에 푹 빠져 계신가요? 자동으로 폴더로 분류됩니다. 중요한 대화에 대한 답글을 추적해야 하나요? 라벨과 필터가 알아서 처리해 줍니다. 완벽한 이메일 초안 작성부터 팀과의 대화 관리까지, 모든 것이 제자리에 딱 들어맞습니다. 간소화된 첨부 파일 처리 기능을 통해 이메일 첨부 파일을 쉽게 찾고 관리할 수 있으며, 시스템에서 복잡한 메타데이터는 모두 자동으로 처리됩니다.

캘린더는 매일매일 바쁜 일정 속에서 든든한 동반자가 되어 줍니다. 더 이상 이중으로 예약된 회의나 시간대 혼란은 없습니다. 팀 동기화를 계획하고 계신가요? 캘린더가 최적의 시간을 찾아줍니다. 정기 워크숍을 진행하시나요? 한 번 설정하면 끝입니다. 계획이 변경되더라도 모두에게 맞는 새로운 시간을 쉽고 빠르게 찾을 수 있습니다. "언제 시간 되세요?"라는 이메일을 끊임없이 주고받는 시대는 이제 끝났습니다.

Google Drive를 파일 저장소에서 디지털 관리 센터로 전환하세요. 모든 문서는 제자리에 있고, 모든 폴더는 이야기를 담고 있습니다. 필요한 사람들과 파일을 공유하세요. 더 이상 "누가 이 파일을 수정할 수 있나요?"라는 혼란은 없습니다. 지난주 회의에서 발표했던 프레젠테이션을 찾고 계신가요? 파일 이름뿐 아니라 파일 내용까지 검색해 보세요. 작은 프로젝트를 진행하든, 산더미 같은 문서를 관리하든, 모든 것이 필요한 곳에 바로 보관됩니다.

TL;DR 설정

참고 : Cline과 같은 AI 어시스턴트의 경우, 전문 설치 지침은 llms-install.md를 참조하세요.

1. Google Cloud 프로젝트 만들기:

   지엑스피1

2. Cline 설정에 추가(예: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json ):

   { "mcpServers": { "google-workspace-mcp": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "/home/aaron/.mcp/google-workspace-mcp:/app/config", "-v", "/home/aaron/Documents/workspace-mcp-files:/app/workspace", "-e", "GOOGLE_CLIENT_ID", "-e", "GOOGLE_CLIENT_SECRET", "-e", "LOG_MODE=strict", "ghcr.io/aaronsb/google-workspace-mcp:latest" ], "env": { "GOOGLE_CLIENT_ID": "123456789012-abcdef3gh1jklmn2pqrs4uvw5xyz6789.apps.googleusercontent.com", "GOOGLE_CLIENT_SECRET": "GOCSPX-abcdefghijklmnopqrstuvwxyz1234" }, "autoApprove": [], "disabled": false } } }

   로깅 모드:

   • normal (기본값): 각 로그 수준에 적합한 콘솔 방법을 사용합니다.

   • strict : 모든 비 JSON-RPC 메시지를 stderr로 라우팅합니다(Claude 데스크톱에 권장)

3. 클라인/클로드 재시작

4. AI에게 "Google 계정을 추가해 줘"라고 말하기만 하면 됩니다. AI가 대화형으로 인증 과정을 안내해 줄 것입니다.

자세한 내용은 자세한 설정 가이드를 참조하세요.

Related MCP server: MCP G Suite Integration

필수 조건

중요한:
MCP 서버를 시작하기 전에 구성 디렉토리(예: ~/.mcp/google-workspace-mcp )를 직접 만들고 사용자 계정이 해당 디렉토리를 소유하고 있는지 확인해야 합니다.
이 디렉토리가 없거나 루트가 소유한 경우, 서버는 구성 파일을 생성하거나 업데이트할 수 없으며 시작에 실패합니다.

이 MCP 서버를 사용하기 전에 Google Workspace API에 액세스할 수 있는 Google Cloud Project를 직접 설정해야 합니다.

1. Google Cloud Console 에서 새 프로젝트를 만듭니다.

2. 필요한 API를 활성화하세요:

   • Gmail API

   • 구글 캘린더 API

   • 구글 드라이브 API

3. OAuth 동의 화면을 구성하세요.

   • "외부"로 설정

   • 자신을 테스트 사용자로 추가하세요

   • Gmail, 캘린더 및 드라이브에 필요한 범위 추가

4. OAuth 2.0 자격 증명을 만듭니다.

   • "데스크톱 응용 프로그램" 유형을 선택하세요

   • 클라이언트 ID와 클라이언트 비밀번호를 기록해 두세요.

   • 리디렉션 URI로 "urn:ietf:wg:oauth:2.0:oob"를 사용합니다(이렇게 하면 대역 외 인증이 가능해집니다).

MCP 서버에는 다음이 필요합니다.

1. 위 단계의 Google OAuth 클라이언트 ID 및 비밀번호

2. 구성을 저장하기 위한 로컬 디렉토리 경로(권장: ~/.mcp/google-workspace-mcp )

참고: 이 서버는 OOB(Out-of-band) 인증 흐름을 사용하므로 각 계정을 처음 설정할 때 승인 코드를 수동으로 복사하여 붙여넣어야 합니다.

Cline과 함께 사용

Cline MCP 설정에 다음 구성을 추가하세요.

파일 관리

서버는 구조화된 방식으로 파일을 자동으로 관리합니다.

WorkspaceManager는 이 구조를 자동으로 생성하고 유지 관리합니다.

• 파일이 다운로드/업로드될 때 필요에 따라 디렉토리를 생성합니다.

• 사용자 이메일별로 파일을 정리합니다

• 임시 파일 정리를 처리합니다

• 적절한 권한을 유지합니다

WORKSPACE_BASE_PATH 환경 변수를 설정하여 작업 공간 위치를 사용자 지정할 수 있습니다.

수동 사용

중요한:
컨테이너를 시작하기 전에 마운트하는 구성 디렉토리(예: ~/.mcp/google-workspace-mcp )가 존재하고 사용자가 소유해야 합니다.
존재하지 않으면 mkdir -p ~/.mcp/google-workspace-mcp && chown $USER ~/.mcp/google-workspace-mcp 로 생성합니다.
디렉토리에 대한 쓰기 권한이 있는 경우에만, 서버는 accounts.json 누락된 경우 자동으로 생성을 시도합니다.

컨테이너를 직접 실행할 수 있습니다.

서버는 자동으로 다음을 수행합니다.

• 필요한 모든 구성 파일을 생성하고 관리합니다.

• 자격 증명 및 토큰의 안전한 저장을 처리합니다.

• 적절한 파일 권한 유지

개발 빌드

로컬 빌드 스크립트

빠르고 CI와 유사한 로컬 빌드 및 Docker 이미지를 생성하려면 제공된 스크립트를 사용하세요.

• 기본적으로 이미지는 google-workspace-mcp:local 로 태그됩니다.

• 자세한 출력(모든 로그를 콘솔에 출력)을 사용하려면 --verbose 추가하세요.

  ./scripts/build-local.sh --verbose

• Docker 이미지 태그를 변경하려면:

  ./scripts/build-local.sh --tag my-custom-tag

• 로그 파일은 검토를 위해 /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 작업 초안 완료:

    • 새로운 초안 만들기

    • 기존 초안 읽기

    • 초안 콘텐츠 업데이트

    • 초안 삭제

    • 초안 보내기

  • 지원 대상:

    • 새로운 이메일 초안

    • 스레딩으로 초안 답글 작성

    • 초안 수정

    • 초안 보내기

라벨 관리

• 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)

  • 캘린더 이벤트 삭제

  • 참석자를 위한 알림 옵션

연락처 운영

• get_workspace_contacts (별칭: get_contacts, list_contacts, fetch_contacts)

  • Google 계정에서 연락처 검색

  • 지원 대상:

    • 기본 연락처 정보(이름, 이메일, 전화번호)

    • 확장된 연락처 정보

    • 대규모 연락처 목록에 대한 페이지 매김

  • 일반적인 사용 사례:

    • 연락처 조회

    • 주소록 관리

    • 연락처 정보 검색

드라이브 운영

파일 관리

• 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 서비스

테스트 전략

단위 테스트 접근 방식

1. 단순화된 모킹

   • 예측 가능한 테스트를 위해 정적 모의 응답을 사용하세요

   • 단위 테스트에서 복잡한 엔드투엔드 시뮬레이션을 피하세요

   • 한 번에 한 가지 기능만 테스트하는 데 집중하세요

   • 간단한 구현으로 외부 종속성(OAuth, 파일 시스템)을 모의합니다.

2. 테스트 조직

   • 기능별 그룹 테스트(예: 계정 작업, 파일 작업)

   • 명확하고 설명적인 테스트 이름을 사용하세요

   • 테스트를 집중하고 분리하세요

   • 테스트 사이에 모의 및 모듈 재설정

3. 모의 관리

   • jest.resetModules()를 사용하여 깨끗한 상태를 보장합니다.

   • 모의 변경 후 모듈 다시 요구

   • 모의 함수 호출을 명시적으로 추적합니다.

   • 함수 호출과 결과를 모두 확인하세요

4. 파일 시스템 테스트

   • 간단한 JSON 구조를 사용하세요

   • 형식보다는 데이터 정확성에 집중하세요

   • 테스트 오류 시나리오(파일 누락, 잘못된 JSON)

   • 구현 세부 정보 없이 파일 작업 확인

5. 토큰 처리

   • 정적 응답을 사용한 모의 토큰 검증

   • 성공 및 실패 시나리오를 별도로 테스트합니다.

   • OAuth 복잡성 없이 토큰 작업 확인

   • 계정 관리자의 토큰 처리 로직에 초점을 맞추세요

테스트 실행

모범 사례

1. 입증

   • MCP 설정에서 자격 증명을 안전하게 저장하세요

   • 최소한으로 필요한 범위를 사용하세요

   • 토큰 새로 고침을 올바르게 처리하세요

2. 오류 처리

   • 응답 상태 확인

   • 인증 오류를 적절하게 처리하세요

   • 적절한 재시도를 구현하세요

3. 구성 및 보안

   • 각 사용자는 자신의 Google Cloud 프로젝트를 유지 관리합니다.

   • MCP 설정에서 OAuth 자격 증명 구성

   • ~/.mcp/google-workspace-mcp에 보안 토큰 저장소

   • 정기적인 토큰 회전

   • 민감한 파일은 절대 git에 커밋하지 마세요

   • 구성 디렉토리에 적절한 파일 권한을 사용하세요

4. 지역 개발 설정

   • MCP 설정에서 OAuth 자격 증명 구성

   • ~/.mcp/google-workspace-mcp 디렉토리를 생성합니다.

   • 민감한 토큰을 버전 제어에서 제외하세요

   • 각 계정에 대한 인증 스크립트 실행

문제 해결

일반적인 설정 문제

1. 구성이 누락되었습니다

   • 오류: "GOOGLE_CLIENT_ID 환경 변수가 필요합니다"

   • 해결 방법: MCP 설정 파일에서 OAuth 자격 증명을 구성합니다(자세한 내용은 docs/API.md 참조).

2. 인증 오류

   • 오류: "잘못된 OAuth 자격 증명"

   • 해결책:

     • Google Cloud 프로젝트가 올바르게 구성되었는지 확인하세요.

     • OAuth 동의 화면에서 자신을 테스트 사용자로 추가했는지 확인하세요.

     • Gmail API와 Google Calendar API가 모두 활성화되어 있는지 확인하세요.

     • MCP 설정의 자격 증명이 OAuth 클라이언트 구성과 일치하는지 확인하세요.

3. 토큰 문제

   • 오류: "토큰 새로 고침에 실패했습니다"

   • 해결 방법: remove_workspace_account 사용하여 계정을 제거하고 다시 인증하세요.

   • Google Cloud 프로젝트에 필요한 API 범위가 활성화되어 있는지 확인하세요.

4. 디렉토리 구조

   • 오류: "디렉토리를 찾을 수 없습니다"

   • 해결 방법: ~/.mcp/google-workspace-mcp가 적절한 권한으로 존재하는지 확인하세요.

   • Docker가 구성 디렉토리를 마운트할 수 있는 권한이 있는지 확인하세요.

추가 도움이 필요하면 오류 처리 설명서를 참조하세요.

특허

MIT 라이선스 - 자세한 내용은 라이선스 파일을 참조하세요.