Google 자동화 MCP

AI 에이전트를 위한 Google Workspace API - GCP 프로젝트가 필요하지 않습니다.

인증을 위해 clasp를 사용합니다. GCP 콘솔, OAuth 동의 화면, 클라이언트 비밀번호가 필요 없습니다. 인증만 하면 바로 사용할 수 있습니다.

빠른 시작

uvx google-automation-mcp auth   # 1. Browser sign-in via clasp
uvx google-automation-mcp        # 4. Run server

첫 실행 시 3단계의 일회성 과정을 거칩니다:

1. gmcp auth - Google 로그인을 위한 브라우저를 엽니다 (clasp OAuth)

2. Apps Script API 활성화 - gmcp auth가 확인 후 https://script.google.com/home/usersettings 에서 ON으로 전환하도록 안내합니다 (5초 소요)

3. 범위 승인 - gmcp auth가 웹 앱 라우터를 배포하고 URL을 출력합니다. 해당 URL을 열고 "허용"을 클릭하여 Gmail/Drive/Sheets/Calendar/Docs/Forms/Tasks 액세스 권한을 부여합니다.

4. 완료 - gmcp 또는 uvx google-automation-mcp를 실행하여 서버를 시작합니다.

언제든지 상태 확인: gmcp status

팁: 설치 후 짧은 별칭 gmcp를 사용하세요.

재인증: 향후 업데이트로 새로운 범위가 추가되면 myaccount.google.com/permissions에서 앱을 취소( "MCP-Router" 찾기)한 다음 gmcp status에서 웹 앱 URL을 다시 방문하세요.

Clasp 라우터 vs REST API

Workspace 도구(Gmail, Drive, Sheets 등)는 두 가지 모드로 작동할 수 있습니다. Clasp 라우터는 기본값이며 GCP 프로젝트가 필요하지 않습니다. 기존 Google API 설정은 GCP 프로젝트 생성, API 활성화, OAuth 동의 화면 구성, 테스트 사용자 추가 및 자격 증명 생성이 필요합니다.

일일 할당량 (무료 개인 Google 계정)

참고: Apps Script 실행 제한은 모든 서비스 간에 공유됩니다. 90분/일 제한은 서비스별이 아닌 총 실행 시간에 적용됩니다. 호출당 약 2초 기준, 하루 약 2,700회의 도구 호출이 가능합니다. 전체 Apps Script 할당량

백엔드 선택

백엔드는 자동으로 선택됩니다: GOOGLE_OAUTH_CLIENT_ID 및 GOOGLE_OAUTH_CLIENT_SECRET이 설정되어 있으면 REST API가 사용됩니다. 그렇지 않으면 Clasp 라우터가 Workspace 호출을 처리합니다.

MCP_USE_ROUTER=true 또는 MCP_USE_ROUTER=false로 특정 백엔드를 강제 지정할 수 있습니다.

자체 OAuth 자격 증명이 필요한 다중 사용자 프로덕션 배포의 경우:

export GOOGLE_OAUTH_CLIENT_ID='...'
export GOOGLE_OAUTH_CLIENT_SECRET='...'
gmcp auth --oauth21

보안: AI는 자격 증명을 절대 볼 수 없습니다

MCP는 보안 경계 역할을 합니다. AI 에이전트는 도구를 호출하고, MCP는 내부적으로 인증을 처리합니다.

MCP 클라이언트 구성

Claude Desktop (원클릭 설치):

google-automation-mcp.dxt를 다운로드하여 엽니다. Claude Desktop이 자동으로 설치됩니다.

Claude Code (~/.mcp.json):

{
  "mcpServers": {
    "google": {
      "type": "stdio",
      "command": "uvx",
      "args": ["google-automation-mcp"]
    }
  }
}

Claude Desktop (수동) (claude_desktop_config.json):

{
  "mcpServers": {
    "google": {
      "command": "uvx",
      "args": ["google-automation-mcp"]
    }
  }
}

Gemini CLI:

gemini extensions install github:sam-ent/google-automation-mcp

사용 가능한 도구 (60)

Gmail (5)

search_gmail_messages · get_gmail_message · send_gmail_message · list_gmail_labels · modify_gmail_labels

Drive (10)

search_drive_files · list_drive_items · get_drive_file_content · create_drive_file · create_drive_folder · delete_drive_file · trash_drive_file · share_drive_file · list_drive_permissions · remove_drive_permission

Sheets (6)

list_spreadsheets · get_sheet_values · update_sheet_values · append_sheet_values · create_spreadsheet · get_spreadsheet_metadata

Calendar (5)

list_calendars · get_events · create_event · update_event · delete_event

Docs (5)

get_doc_content · search_docs · create_doc · modify_doc_text · append_doc_text

Forms (4)

get_form · create_form · add_form_question · get_form_responses

Tasks (6)

list_task_lists · get_tasks · create_task · update_task · delete_task · complete_task

Apps Script (17)

list_script_projects · get_script_project · get_script_content · create_script_project · update_script_content · delete_script_project · run_script_function · create_deployment · list_deployments · update_deployment · delete_deployment · list_versions · create_version · get_version · list_script_processes · get_script_metrics · generate_trigger_code

Auth (2)

start_google_auth · complete_google_auth

다중 사용자 지원

모든 도구는 사용자별 자격 증명 격리를 위해 user_google_email을 허용합니다:

search_gmail_messages(user_google_email="alice@example.com", query="is:unread")
search_gmail_messages(user_google_email="bob@example.com", query="is:unread")

자격 증명은 별도로 저장됩니다: ~/.secrets/google-automation-mcp/credentials/{email}.json

Apps Script: Google Workspace 확장

Apps Script 도구를 사용하면 REST API가 할 수 없는 Google 앱 내부에서 실행되는 코드를 배포할 수 있습니다:

# Create a bound script with custom function
create_script_project(title="Validator", parent_id="SPREADSHEET_ID")
update_script_content(script_id="...", files=[{
    "name": "Code",
    "type": "SERVER_JS",
    "source": "function VALIDATE_EMAIL(e) { return /^[^@]+@[^@]+\\.[^@]+$/.test(e); }"
}])

제한 사항

**run_script_function**은 스크립트당 일회성 설정이 필요합니다: script.google.com에서 스크립트 열기 -> 프로젝트 설정 -> GCP 프로젝트 변경 -> API 실행 파일로 배포. 설정이 완료되면 함수를 반복적으로 호출할 수 있습니다. 다른 모든 도구는 이 설정 없이 작동합니다.

CLI 참조

짧은 별칭: gmcp (또는 전체 이름: google-automation-mcp)

gmcp                 # Run server
gmcp setup           # Interactive setup wizard
gmcp auth            # Authenticate with clasp
gmcp auth --oauth21  # OAuth 2.1 for production
gmcp status          # Check auth status
gmcp version         # Show version

개발

git clone https://github.com/sam-ent/google-automation-mcp.git
cd google-automation-mcp
uv sync
uv run pytest tests/ -v  # 183 tests

감사의 말

Taylor Wilsdon의 google_workspace_mcp를 기반으로 구축되었습니다 (MIT 라이선스).

라이선스

MIT