Google Workspace API MCP

Google Workspace API를 사용해 Google Drive 파일 검색, Google Docs 문서 조회 및 편집, Google Sheets 스프레드시트 조회 및 수정을 제공하는 MCP 서버입니다.

주요 기능

• google_auth_start_oauth: 사용자의 Google 계정 OAuth 동의 절차를 시작하고 refresh token을 로컬 파일에 저장합니다.
• google_drive_search_files: Google Drive에서 파일 이름 또는 본문 검색으로 문서, 스프레드시트, 기타 파일을 찾습니다.
• google_drive_get_file: Drive 파일 ID로 파일 메타데이터, 웹 링크, 소유자, 권한 정보를 조회합니다.
• google_docs_get_document: Google Docs 문서 구조와 추출된 일반 텍스트를 조회합니다.
• google_docs_create_document: 새 Google Docs 문서를 만들고 선택적으로 초기 텍스트를 삽입합니다.
• google_docs_append_text: 기존 Google Docs 문서 끝에 텍스트를 추가합니다.
• google_docs_insert_text: 지정한 Google Docs 구조 인덱스에 텍스트를 삽입합니다.
• google_docs_replace_text: 문서 안의 특정 텍스트를 전체 치환합니다.
• google_sheets_create_spreadsheet: 새 Google Sheets 스프레드시트를 만들고 선택적으로 시트 이름을 지정합니다.
• google_sheets_add_sheet: 기존 Google Sheets 스프레드시트에 새 시트 탭을 추가합니다.
• google_sheets_list_sheets: 스프레드시트의 시트 목록, 시트 ID, 행/열 크기를 조회합니다.
• google_sheets_delete_sheet: 시트 ID 또는 시트 이름으로 시트 탭을 삭제합니다.
• google_sheets_rename_sheet: 시트 ID 또는 기존 시트 이름으로 시트 탭 이름을 변경합니다.
• google_sheets_get_values: A1 표기법 범위의 셀 값을 읽습니다.
• google_sheets_update_values: 지정한 범위의 셀 값을 덮어씁니다.
• google_sheets_clear_values: 지정한 범위의 값을 비웁니다.
• google_sheets_append_values: 지정한 범위에 행 데이터를 추가합니다.
• google_sheets_upload_csv: 로컬 CSV 파일을 새 스프레드시트 또는 기존 Google Sheets 탭에 업로드합니다.
• google_sheets_format_header: 헤더 행을 굵게 표시하고 배경색과 고정 행을 설정합니다.
• google_sheets_auto_resize_columns: 지정한 시트의 열 너비를 자동 맞춤합니다.

사전 준비: Google Cloud 연동 가이드

이 MCP는 Google Drive, Docs, Sheets 호출에 OAuth 또는 서비스 계정 인증 방식을 사용합니다.
Google Cloud Console에서 필요한 사항을 준비하는 절차는 다음 문서를 참고하세요.

• Google Cloud API Key, OAuth, 서비스 계정 준비 가이드

서비스 계정과 OAuth 중 무엇을 선택할지

두 방식 모두 Drive, Docs, Sheets API를 사용할 수 있지만 접근 주체와 운영 방식이 다릅니다. 개인 드라이브를 자연스럽게 다루려면 OAuth가 편하고, 공유된 문서나 자동화 작업을 안정적으로 처리하려면 서비스 계정이 단순합니다.

| 구분 | 서비스 계정 | OAuth 사용자 인증 | | --- | --- | --- | | 접근 주체 | 별도의 Google 서비스 계정 | 로그인하고 동의한 사용자 계정 | | 접근 범위 | 서비스 계정에 공유된 파일/폴더 | 사용자가 동의한 범위 안의 사용자 Drive | | 초기 설정 | 키 파일 또는 서비스 계정 JSON 필요 | OAuth Client ID/Secret 필요 | | 사용자 동의 | 필요 없음 | 최초 1회 브라우저 동의 필요 | | 파일 생성 위치 | 서비스 계정 소유 또는 공유 드라이브/공유 위치 | 사용자 계정의 Google Drive | | 운영 편의성 | 서버/배치/CI에 적합 | 개인 사용, 로컬 MCP, 대화형 작업에 적합 | | 보안 관리 | private key 관리가 중요 | refresh token 파일 관리가 중요 |

서비스 계정이 좋은 경우:

• 특정 폴더나 문서를 서비스 계정에 공유해 두고 반복적으로 자동 처리할 때
• 팀/조직 자동화, 배치 작업, CI, 서버 환경에서 사용할 때
• 사용자 브라우저 동의 없이 항상 같은 권한으로 동작해야 할 때
• 접근 대상을 명시적으로 제한하고 싶을 때

OAuth가 좋은 경우:

• MCP를 본인 Google 계정의 Drive, Docs, Sheets 작업 도구로 쓰고 싶을 때
• 새 문서나 스프레드시트가 내 Google Drive에 바로 생성되어야 할 때
• 파일마다 서비스 계정 이메일에 공유 권한을 주는 과정이 번거로울 때
• 로컬 개발, 개인 자동화, 코딩 에이전트와 같은 대화형 환경에서 사용할 때

선택이 애매하면 개인 사용은 OAuth부터 시작하고, 팀 자동화나 서버 배포는 서비스 계정을 우선 고려하세요.

MCP 설정(서비스 계정으로 사용하는 경우)

서비스 계정이 생성되고 준비가 완료되었다면 아래와 같이 세가지 방법으로 MCP 클라이언트에 설정할 수 있습니다.

1. MCP 설정에 직접 입력

서비스 계정 JSON에서 client_email, private_key, project_id 값을 꺼내 MCP 설정의 환경 변수로 넣을 수 있습니다.

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "google-workspace-api-mcp"],
      "env": {
        "GOOGLE_CLIENT_EMAIL": "[email protected]",
        "GOOGLE_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\\nYOUR_PRIVATE_KEY_CONTENT\\n-----END PRIVATE KEY-----\\n",
        "GOOGLE_PROJECT_ID": "your-google-cloud-project-id"
      }
    }
  }
}

GOOGLE_PRIVATE_KEY의 줄바꿈은 위 예시처럼 \\n으로 입력하면 됩니다. 서버가 실행 시 실제 개행 문자로 변환합니다.

2. 서비스 계정 JSON 전체 입력

서비스 계정 JSON 파일 전체를 base64로 인코딩해 GOOGLE_SERVICE_ACCOUNT_JSON에 넣을 수 있습니다.

PowerShell:

[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes((Get-Content .\\service-account.json -Raw)))

MCP 설정:

{
   "mcpServers": {
      "google-workspace": {
         "command": "npx",
         "args": ["-y", "google-workspace-api-mcp"],
         "env": {
            "GOOGLE_SERVICE_ACCOUNT_JSON": "base64_encoded_service_account_json"
         }
      }
   }
}

3. 키 파일 경로 사용

Google Cloud Console에서 받은 서비스 계정 JSON 키 파일을 안전한 위치에 저장한 뒤, MCP 설정에 파일 경로를 전달합니다.

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "google-workspace-api-mcp"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY_FILE": "/path/to/service-account.json"
      }
    }
  }
}

GOOGLE_APPLICATION_CREDENTIALS도 동일하게 사용할 수 있습니다.

{
  "env": {
    "GOOGLE_APPLICATION_CREDENTIALS": "/secure/path/google-workspace-service-account.json"
  }
}

서비스 계정 JSON, private key, 키 파일은 README, 소스 코드, 공개 저장소에 커밋하지 마세요. MCP 클라이언트의 secret/env 관리 기능이나 로컬 환경 변수를 사용하세요.

로컬 개발

저장소를 받은 뒤 패키지 디렉터리에서 실행합니다.

cd google-workspace-api-mcp
npm install
npm run build
npm start

로컬 빌드 결과물을 직접 실행하는 MCP 설정 예시:

{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["/absolute/path/to/google-workspace-api-mcp/build/index.js"],
      "env": {
        "GOOGLE_CLIENT_EMAIL": "[email protected]",
        "GOOGLE_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\\nYOUR_PRIVATE_KEY_CONTENT\\n-----END PRIVATE KEY-----\\n",
        "GOOGLE_PROJECT_ID": "your-google-cloud-project-id"
      }
    }
  }
}

args의 경로는 사용자의 실제 프로젝트 디렉터리에 있는 build/index.js 절대 경로로 바꾸면 됩니다. Windows라면 예를 들어 C:\\path\\to\\google-workspace-api-mcp\\build\\index.js처럼 적습니다.

Docker

이미지 빌드:

docker build -t google-workspace-api-mcp .

Docker 기반 MCP 설정 예시:

{
  "mcpServers": {
    "google-workspace": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GOOGLE_CLIENT_EMAIL=your-service-account@your-project.iam.gserviceaccount.com",
        "-e",
        "GOOGLE_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----\\nYOUR_PRIVATE_KEY_CONTENT\\n-----END PRIVATE KEY-----\\n",
        "-e",
        "GOOGLE_PROJECT_ID=your-google-cloud-project-id",
        "google-workspace-api-mcp"
      ]
    }
  }
}

MCP 설정(OAuth 사용자 인증)

서비스 계정 대신 사용자의 Google 계정으로 Drive, Docs, Sheets에 접근하려면 OAuth 클라이언트를 설정한 뒤 MCP 도구로 사용자 동의 절차를 시작할 수 있습니다.

이 방식으로 생성한 문서와 스프레드시트는 인증한 사용자 계정의 Google Drive에 생성됩니다. OAuth 설정이 있으면 서비스 계정 설정보다 OAuth 인증을 우선 사용합니다.

필수 환경 변수:

• GOOGLE_OAUTH_CLIENT_ID: Google Cloud OAuth 클라이언트 ID
• GOOGLE_OAUTH_CLIENT_SECRET: Google Cloud OAuth 클라이언트 보안 비밀

선택 환경 변수:

• GOOGLE_OAUTH_TOKEN_PATH: OAuth 토큰을 저장할 로컬 파일 경로입니다. 기본값은 사용자 홈 디렉터리의 .google-workspace-api-mcp/token.json입니다.
• GOOGLE_OAUTH_REFRESH_TOKEN: 이미 발급받은 refresh token을 직접 넣고 싶을 때 사용합니다.
• GOOGLE_OAUTH_ACCESS_TOKEN: 기존 access token이 있을 때만 입력합니다. 만료되어도 refresh token으로 갱신됩니다.
• GOOGLE_OAUTH_REDIRECT_URI: 직접 refresh token을 넣는 경우 사용할 redirect URI입니다. 기본값은 http://127.0.0.1입니다.

MCP 설정 예시:

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "google-workspace-api-mcp"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "your-oauth-client-id.apps.googleusercontent.com",
        "GOOGLE_OAUTH_CLIENT_SECRET": "your-oauth-client-secret",
        "GOOGLE_OAUTH_TOKEN_PATH": "/absolute/path/to/google-workspace-api-mcp-token.json"
      }
    }
  }
}

MCP 클라이언트에 등록한 뒤 google_auth_start_oauth 도구를 호출하면 브라우저에서 Google 동의 화면이 열립니다. 동의가 완료되면 refresh token이 GOOGLE_OAUTH_TOKEN_PATH에 저장되고, 이후 Drive, Docs, Sheets 도구가 같은 토큰을 자동으로 사용합니다.

브라우저가 자동으로 열리지 않으면 도구 결과의 authUrl을 브라우저 주소창에 직접 붙여 넣어 동의 절차를 계속 진행하세요. 자동 열기 시도 결과는 browserOpenSucceeded와 browserOpenError에서 확인할 수 있습니다.

로컬 콜백은 http://127.0.0.1:{port}/oauth2callback 형식으로 잠시 열립니다. Google Cloud Console에서 OAuth 클라이언트를 만들 때 데스크톱 앱 유형을 사용하면 로컬 콜백 흐름에 적합합니다.

적용 후 동작 확인

MCP 클라이언트에 등록한 뒤 다음 순서로 확인합니다.

1. google_drive_search_files
   • 서비스 계정에 공유한 파일명 일부로 검색합니다.
2. google_drive_get_file
   • 검색된 파일 ID로 메타데이터를 확인합니다.
3. google_docs_get_document
   • Google Docs 문서 ID로 문서 내용을 읽습니다.
4. google_sheets_get_values
   • Google Sheets ID와 범위로 값을 읽습니다.

검색 결과가 비어 있으면 대부분 다음 중 하나입니다.

• 서비스 계정 이메일에 파일/폴더가 공유되지 않았습니다.
• Drive, Docs, Sheets API가 프로젝트에서 사용 설정되지 않았습니다.
• 잘못된 프로젝트의 서비스 계정 키를 사용했습니다.
• MCP 클라이언트 env 설정이 적용되지 않았습니다.

JSON 호출 예시

Drive 파일 검색

{
  "query": "회의록",
  "mime_type": "application/vnd.google-apps.document",
  "page_size": 10
}

Google Docs 문서 생성

{
  "title": "주간 업무 보고",
  "text": "이번 주 진행 상황\n- MCP 서버 구성\n- Google Docs 연동 테스트\n"
}

Google Docs 텍스트 추가

{
  "document_id": "google_docs_document_id",
  "text": "\n다음 주 계획\n- 배포 검증\n- 사용자 문서 보강\n"
}

Google Sheets 값 읽기

{
  "spreadsheet_id": "google_sheets_spreadsheet_id",
  "range": "Sheet1!A1:D20"
}

Google Sheets 행 추가

{
  "spreadsheet_id": "google_sheets_spreadsheet_id",
  "range": "Sheet1!A:D",
  "values": [
    ["날짜", "항목", "상태", "메모"],
    ["2026-06-27", "MCP 배포 준비", "완료", "npx 실행 구성"]
  ],
  "value_input_option": "USER_ENTERED"
}

Google Sheets CSV upload

Create a new spreadsheet from a local CSV file:

{
  "file_path": "./data/report.csv",
  "spreadsheet_title": "Imported report",
  "sheet_name": "Report",
  "value_input_option": "USER_ENTERED",
  "auto_resize": true,
  "verify": true
}

Upload a CSV file into an existing spreadsheet tab:

{
  "file_path": "./data/report.csv",
  "spreadsheet_id": "google_sheets_spreadsheet_id",
  "sheet_name": "Import",
  "clear_before_upload": true,
  "create_sheet_if_missing": true,
  "delimiter": ",",
  "encoding": "utf8"
}

LLM 채팅 프롬프트 예시

MCP가 연결된 LLM 채팅에서 아래처럼 자연어로 요청할 수 있습니다.

내 Google Drive에서 "분기 보고서"가 들어간 Google Docs 문서를 찾아서 최근 수정일 기준으로 정리해줘.

이 문서 ID의 내용을 읽고 핵심 결정 사항과 할 일을 요약해줘.

새 Google Docs 문서를 만들고 제목은 "프로젝트 킥오프 메모"로 해줘. 본문에는 참석자, 목표, 다음 액션 섹션을 넣어줘.

이 스프레드시트의 Sheet1!A1:F50 범위를 읽고 상태가 지연인 항목만 표로 정리해줘.

이 스프레드시트 Sheet1에 오늘 날짜, 작업명, 상태, 메모를 한 행으로 추가해줘.

배포

npm run build
npm pack --dry-run
npm login
npm publish

scope 패키지로 이름을 바꾸는 경우:

npm publish --access public

주의 사항

• Google Workspace API 사용량과 조직 정책에 따라 할당량 제한이나 접근 제한이 발생할 수 있습니다.
• 서비스 계정은 명시적으로 공유받은 파일과 폴더에만 접근할 수 있습니다.
• 문서 편집 도구는 Google Docs API의 구조 인덱스를 사용합니다. 일반적인 문서 시작 위치는 1입니다.
• 민감한 문서와 스프레드시트를 다룰 때는 MCP 클라이언트 로그, 터미널 기록, 환경 변수 노출 범위를 확인하세요.