hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Integrations

Allows querying emails with advanced search, reading full email content and attachments, creating and managing drafts, replying to emails, archiving emails, handling attachments, and bulk operations support
Allows listing available calendars, viewing calendar events, creating new events, deleting events, supporting multiple calendars, and custom timezone support

MCP Google Workspace 서버

Google Workspace 서비스를 위한 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버는 MCP 프로토콜을 통해 Gmail 및 Google 캘린더와 상호작용하는 도구를 제공합니다.

특징

여러 Google 계정 지원
- 여러 Google 계정을 사용하고 전환하세요
- 각 계정에는 사용자 정의 메타데이터와 설명이 있을 수 있습니다.
Gmail 통합
- 고급 검색으로 이메일 쿼리하기
- 전체 이메일 내용과 첨부 파일을 읽어보세요
- 초안을 만들고 관리하세요
- 이메일에 답장하기
- 이메일 보관
- 핸들 부착물
- 대량 작업 지원
캘린더 통합
- 사용 가능한 캘린더 나열
- 캘린더 이벤트 보기
- 새로운 이벤트 만들기
- 이벤트 삭제
- 여러 캘린더 지원
- 사용자 정의 시간대 지원

예시 프롬프트

AI 비서에게 다음의 예시 프롬프트를 시도해 보세요.

지메일

"내 최신 읽지 않은 메시지 검색"
"스크럼 마스터로부터 온 이메일을 검색하세요"
"회계 부서의 모든 이메일을 검색합니다"
"ABC에 대한 이메일을 가져와 요약하세요"
"앨리스의 마지막 이메일에 대한 멋진 답장을 작성하고 초안을 업로드하세요"
"밥의 이메일에 감사 편지를 첨부하여 답장하세요. 임시 보관함에 보관하세요."

달력

"내일 일정은 뭐야?"
"다음 주 내 개인 계정의 가족 일정을 확인하세요"
"다음 주에 팀과 2시간 동안 이벤트를 계획해야 합니다. 시간대를 제안해 주세요."

필수 조건

노드.js >= 18
Gmail 및 캘린더 API가 활성화된 Google Cloud 프로젝트
Google API에 대한 OAuth 2.0 자격 증명

설치

저장소를 복제합니다.지엑스피1
종속성 설치:
npm install
TypeScript 코드를 작성합니다.
npm run build

구성

OAuth 2.0 설정

Google Workspace(G Suite) API를 사용하려면 OAuth2 인증이 필요합니다. 다음 단계에 따라 인증을 설정하세요.

OAuth2 자격 증명을 만듭니다.
- Google Cloud Console 로 이동
- 새 프로젝트를 만들거나 기존 프로젝트를 선택하세요
- 프로젝트에 Gmail API와 Google 캘린더 API를 활성화하세요
- "자격 증명" → "자격 증명 만들기" → "OAuth 클라이언트 ID"로 이동하세요.
- 애플리케이션 유형으로 "데스크톱 앱" 또는 "웹 애플리케이션"을 선택하세요.
- 필수 정보로 OAuth 동의 화면 구성
- 권한이 있는 리디렉션 URI를 추가합니다(로컬 개발을 위해 http://localhost:4100/code 포함)
필요한 OAuth2 범위:
[ "openid", "https://mail.google.com/", "https://www.googleapis.com/auth/calendar", "https://www.googleapis.com/auth/userinfo.email" ]
Google OAuth 2.0 자격 증명을 사용하여 프로젝트 루트에 .gauth.json 파일을 만듭니다.
{ "installed": { "client_id": "your_client_id", "project_id": "your_project_id", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://oauth2.googleapis.com/token", "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "client_secret": "your_client_secret", "redirect_uris": ["http://localhost:4100/code"] } }
서버를 사용할 수 있는 Google 계정을 지정하려면 .accounts.json 파일을 만듭니다.
{ "accounts": [ { "email": "your.email@gmail.com", "account_type": "personal", "extra_info": "Primary account with Family Calendar" } ] }
여러 계정을 지정할 수 있습니다. Google Auth 앱에서 해당 계정에 대한 접근 권한이 있는지 확인하세요. extra_info 필드는 AI에게 계정에 대한 정보(예: 특정 캘린더 사용 여부)를 제공할 수 있으므로 특히 유용합니다.

클로드 데스크톱 구성

Claude Desktop을 구성하여 mcp-google-workspace 서버를 사용합니다.

MacOS의 경우: ~/Library/Application\ Support/Claude/claude_desktop_config.json 편집하세요.

Windows에서: %APPDATA%/Claude/claude_desktop_config.json 편집하세요.

{
  "mcpServers": {
    "mcp-google-workspace": {
      "command": "<dir_to>/mcp-google-workspace/launch"
    }
  }
}

{
  "mcpServers": {
    "mcp-google-workspace": {
      "command": "npx",
      "args": [
        "mcp-google-workspace"
      ]
    }
  }
}

용법

서버를 시작합니다:
npm start
선택 인수:
- --gauth-file : OAuth2 자격 증명 파일의 경로(기본값: ./.gauth.json)
- --accounts-file : 계정 구성 파일 경로(기본값: ./.accounts.json)
- --credentials-dir : OAuth 자격 증명을 저장할 디렉토리(기본값: 현재 디렉토리)
서버가 시작되고 stdin/stdout을 통해 MCP 명령을 수신합니다.
각 계정을 처음 실행하면 다음이 수행됩니다.
- OAuth2 인증을 위해 브라우저 창을 엽니다.
- OAuth2 콜백을 위해 포트 4100에서 수신합니다.
- 나중에 사용할 자격 증명을 .oauth2.{email}.json 이라는 파일에 저장합니다.

사용 가능한 도구

계정 관리

gmail_list_accounts / calendar_list_accounts
- 구성된 모든 Google 계정 나열
- 계정 메타데이터 및 설명 보기
- user_id가 필요하지 않습니다

Gmail 도구

gmail_query_emails
- Gmail의 쿼리 구문을 사용하여 이메일을 검색합니다(예: 'is:unread', 'from: example@gmail.com ', 'newer_than:2d', 'has:attachment')
- 이메일을 역순으로 반환합니다.
- 메타데이터와 콘텐츠 요약이 포함되어 있습니다.
gmail_get_email
- ID로 전체 이메일 내용 검색
- 전체 메시지 본문과 첨부 파일 정보가 포함되어 있습니다.
gmail_bulk_get_emails
- 단일 요청으로 ID로 여러 이메일 검색
- 일괄 처리에 효율적
gmail_create_draft
- 새로운 이메일 초안 만들기
- CC 수신자 지원
gmail_delete_draft
- ID로 임시 이메일 삭제
gmail_reply
- 기존 이메일에 답장하기
- 즉시 보내기 또는 초안으로 저장 옵션
- CC를 통한 "모두에게 답장" 지원
gmail_get_attachment
- 이메일 첨부 파일 다운로드
- 디스크에 저장하거나 내장 리소스로 반환
gmail_bulk_save_attachments
- 단일 작업으로 여러 첨부 파일 저장
gmail_archive / gmail_bulk_archive
- 받은 편지함에서 이메일 옮기기
- 개별 또는 대량 작업 지원

캘린더 도구

calendar_list
- 접근 가능한 모든 캘린더 나열
- 캘린더 메타데이터, 액세스 역할 및 시간대 정보가 포함됩니다.
calendar_get_events
- 날짜 범위 내 이벤트 검색
- 여러 캘린더 지원
- 필터 옵션(삭제된 이벤트, 최대 결과)
- 시간대 사용자 정의
calendar_create_event
- 새 캘린더 이벤트 만들기
- 참석자 및 알림 지원
- 위치 및 설명 필드
- 시간대 처리
calendar_delete_event
- ID로 이벤트 삭제
- 취소 알림 옵션

개발

소스 코드는 src/ 디렉토리 아래의 TypeScript에 있습니다.
빌드 출력은 dist/ 디렉토리로 이동합니다.
더 나은 모듈성을 위해 ES 모듈을 사용합니다.
Google API 모범 사례를 따릅니다.

프로젝트 구조

mcp-google-workspace/
├── src/
│   ├── server.ts           # Main server implementation
│   ├── services/
│   │   └── gauth.ts        # Google authentication service
│   ├── tools/
│   │   ├── gmail.ts        # Gmail tools implementation
│   │   └── calendar.ts     # Calendar tools implementation
│   └── types/
│       └── tool-handler.ts # Common types and interfaces
├── .gauth.json             # OAuth2 credentials
├── .accounts.json          # Account configuration
├── package.json            # Project dependencies
└── tsconfig.json           # TypeScript configuration

개발 명령

npm run build : TypeScript 코드 빌드
npm start : 서버 시작
npm run dev : 자동 재로드로 개발 모드로 시작

기여하다

저장소를 포크하세요
기능 브랜치 생성
변경 사항을 커밋하세요
지점으로 밀어 넣기
풀 리퀘스트 만들기

특허

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

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

MCP 프로토콜을 사용하여 Gmail 및 Google 캘린더와 상호 작용하고, 자연어를 통한 여러 Google 계정, 이메일 관리 및 캘린더 작업을 지원합니다.

Related Resources

Reddit Discussion about this server

MCP Google Workspace Server