Google Workspace MCP 서버

다중 계정 자격 증명 라우팅, AI 소비를 위한 응답 형식 지정 및 상황별 안내를 처리하는 단일 MCP 서버를 통해 AI 에이전트에게 Gmail, 캘린더, 드라이브 등 Google Workspace에 대한 전체 액세스 권한을 부여하세요.

Google 공식 Workspace CLI (gws)를 기반으로 구축되었으므로 Google의 발전과 함께 API 지원 범위도 확장됩니다. 이 서버는 선언적 YAML을 완전히 기능적인 MCP 도구로 변환하는 매니페스트 기반 팩토리를 사용합니다. 즉, 새로운 Google API 작업을 추가하는 것은 코드 변경이 아닌 구성 변경입니다.

이 MCP 서버를 사용하는 이유

사용자용: 한 번의 설치로 AI 에이전트가 귀하의 Google 계정에 실제 인증된 액세스 권한을 갖게 됩니다. 이메일 검색, 캘린더 확인, 드라이브 파일 관리, 다단계 워크플로 연결 등을 자연스러운 대화를 통해 수행할 수 있습니다.

팀용: 다중 계정 지원을 통해 에이전트가 개인 계정과 업무 계정에서 동시에 작업할 수 있으며, 계정별 자격 증명 격리 및 XDG 호환 저장소를 제공합니다.

개발자용: 팩토리 아키텍처 덕분에 지원 범위가 빠르게 확장됩니다. Google의 Workspace CLI는 이미 15개 이상의 서비스와 수백 개의 API 작업을 지원합니다. 매니페스트는 노출할 작업을 선별하고, 패치는 도메인별 형식을 추가하며, 기본값은 나머지 모든 것을 처리합니다.

Related MCP server: MCP G Suite Integration

사용 가능한 기능

3개 핵심 서비스에 걸친 5개 도구, 32개 이상의 작업:

도구	작업	기능
`manage_email`	search, read, send, reply, replyAll, forward, triage, trash, untrash, modify, labels, threads, getThread	전체 Gmail — 검색, 읽기, 작성, 스레드 관리, 라벨 관리
`manage_calendar`	list, agenda, get, create, quickAdd, update, delete, calendars, freebusy	캘린더 CRUD, 자연어 이벤트 생성, 가용성 확인
`manage_drive`	search, get, upload, download, copy, delete, export, listPermissions, share, unshare	파일 관리, Google 문서 내보내기, 공유 및 권한
`manage_accounts`	list, authenticate, remove, status, refresh, scopes	다중 계정 수명 주기 — 계정 추가, 자격 증명 및 범위 관리
`queue_operations`	—	`$N.field` 결과 참조를 사용하여 작업을 순차적으로 연결

모든 응답에는 다음 단계(next-steps) 안내가 포함되어 있어 에이전트가 다음에 무엇을 할 수 있는지 항상 파악할 수 있습니다.

작동 방식

                          ┌─────────────────────────┐
MCP Client ──stdio──▶     │  manifest.yaml           │
                          │  (52 operations declared) │
                          └────────┬────────────────┘
                                   │
                          ┌────────▼────────────────┐
                          │  Factory Generator       │
                          │  schemas + handlers      │
                          └────────┬────────────────┘
                                   │
                    ┌──────────────┼──────────────┐
                    ▼              ▼              ▼
              ┌──────────┐  ┌──────────┐  ┌──────────┐
              │  Gmail   │  │ Calendar │  │  Drive   │
              │  Patch   │  │  Patch   │  │  Patch   │
              └────┬─────┘  └────┬─────┘  └────┬─────┘
                   │             │             │
                   └──────┬──────┘──────┬──────┘
                          ▼             ▼
                    Account Router ──▶ gws CLI ──▶ Google APIs

팩토리는 시작 시 YAML 매니페스트를 읽고 MCP 도구 스키마와 요청 핸들러를 생성합니다. 패치는 Gmail 검색 하이드레이션, 캘린더 형식 지정, 드라이브 파일 유형 감지 등 필요한 곳에 도메인별 동작을 추가합니다. 패치가 없는 작업은 자동으로 적절한 기본값을 적용받습니다.

기본 엔진은 전체 Google Workspace API 표면을 래핑하는 Rust 바이너리인 Google의 @googleworkspace/cli입니다. MCP 서버는 노출할 작업을 선별하고 AI 소비를 위해 응답을 구성합니다.

설치

MCPB 번들 (Claude Desktop 및 기타 MCP 클라이언트)

최신 릴리스에서 플랫폼용 .mcpb 번들을 다운로드하세요:

플랫폼	파일
macOS (Apple Silicon)	`google-workspace-mcp-darwin-arm64.mcpb`
macOS (Intel)	`google-workspace-mcp-darwin-x64.mcpb`
Linux x64	`google-workspace-mcp-linux-x64.mcpb`
Linux ARM64	`google-workspace-mcp-linux-arm64.mcpb`
Windows x64	`google-workspace-mcp-windows-x64.mcpb`

Claude Desktop에서 .mcpb 파일을 앱으로 드래그하면 Google OAuth 자격 증명을 묻는 메시지가 표시되며, 그 후 바로 사용할 수 있습니다. .mcpb 확장을 지원하는 다른 MCP 클라이언트도 동일한 방식으로 설치할 수 있습니다. 번들에는 서버, gws 바이너리 및 모든 종속성이 포함되어 있습니다.

Claude Code / npm

npm install @aaronsb/google-workspace-mcp

또는 직접 실행:

npx @aaronsb/google-workspace-mcp

사전 요구 사항

Node.js 18 이상
Google Cloud OAuth 자격 증명 — console.cloud.google.com/apis/credentials에서 생성:
- OAuth 2.0 클라이언트 ID(데스크톱 애플리케이션) 생성
- 원하는 API(Gmail, 캘린더, 드라이브, 시트 등) 활성화
환경 변수 설정:

export GOOGLE_CLIENT_ID="your-client-id"
export GOOGLE_CLIENT_SECRET="your-client-secret"

MCP 클라이언트 구성

Claude Desktop

claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["@aaronsb/google-workspace-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Claude Code

.mcp.json에 추가:

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["@aaronsb/google-workspace-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

사용법

계정 추가 (OAuth를 위해 브라우저가 열림):

manage_accounts { "operation": "authenticate" }

그런 다음 계정 이메일과 함께 도구를 사용하세요:

manage_email    { "operation": "triage", "email": "you@gmail.com" }
manage_calendar { "operation": "agenda", "email": "you@gmail.com" }
manage_drive    { "operation": "search", "email": "you@gmail.com", "query": "quarterly report" }

다단계 워크플로

결과 참조를 사용하여 작업을 연결하세요. 한 단계의 출력이 다음 단계로 전달됩니다:

{
  "operations": [
    { "tool": "manage_email", "args": { "operation": "search", "email": "you@gmail.com", "query": "from:boss subject:review" }},
    { "tool": "manage_email", "args": { "operation": "read", "email": "you@gmail.com", "messageId": "$0.messageId" }}
  ]
}

지원 범위 확장

이 서버는 이미 15개 이상의 Google 서비스(시트, 문서, 할 일, 주소록, 채팅 등)를 지원하는 gws CLI에서 작업을 검색합니다. 지원 범위 추가는 매니페스트 편집만으로 가능합니다:

make manifest-discover   # Find all 287+ available operations
make manifest-lint       # Validate the curated manifest
make test                # Verify everything works

새로운 작업은 자동으로 기본 형식이 지정됩니다. 도메인별 표현이 필요한 경우에만 패치를 추가하세요.

데이터 저장소

XDG 기본 디렉터리 사양을 따릅니다:

데이터	위치
계정 레지스트리	`~/.config/google-workspace-mcp/accounts.json`
자격 증명	`~/.local/share/google-workspace-mcp/credentials/`

자격 증명은 표준 OAuth 토큰이 포함된 계정별 파일입니다. 프로젝트 디렉터리에는 비밀 정보가 저장되지 않습니다.

라이선스

MIT

Google Workspace MCP Server