google-drive-mcp

Claude Code에 전체 범위의 Google Drive 액세스 권한을 부여하는 로컬 MCP 서버 — 검색, 읽기, 업로드, 이름 변경, 이동, 공유 권한 변경 등을 수행할 수 있습니다. 이미 Drive에 존재하는 파일(이 앱이 생성한 파일뿐만 아니라)에도 적용됩니다.

의도적으로 광범위한 https://www.googleapis.com/auth/drive 범위를 요청합니다. 이 서버가 구축된 작업(기존 강의 파일의 이름 변경, 이동, 공유 변경)은 좁은 drive.file 범위로는 불가능하기 때문입니다.

일회성 설정

한 번만 수행하면 됩니다. 이후 모든 Claude Code 세션에서 google-drive 도구를 사용할 수 있습니다.

1단계 — Google Cloud 프로젝트 생성 (이미 있는 경우 건너뛰기)

1. https://console.cloud.google.com/로 이동합니다.

2. 상단 바 → 프로젝트 드롭다운 → 새 프로젝트.

3. app-integrations와 같은 이름으로 지정 → 만들기. 몇 초 기다린 후, 상단 바에서 해당 프로젝트가 선택되었는지 확인합니다.

2단계 — Google Drive API 사용 설정

1. https://console.cloud.google.com/apis/library/drive.googleapis.com로 이동합니다.

2. 프로젝트가 선택되었는지 확인 → 사용 설정을 클릭합니다.

3단계 — OAuth 동의 화면 구성

1. https://console.cloud.google.com/auth/overview (API 및 서비스 → OAuth 동의 화면)로 이동합니다.

2. 메시지가 표시되면 사용자 유형: 외부 → 만들기를 선택합니다. (개인 Google 계정의 경우 외부로 해도 괜찮습니다. '테스트 사용자'로 등록하면 됩니다.)

3. 필수 입력란을 작성합니다:

   • 앱 이름: google-drive-mcp (아무 이름이나 가능)

   • 사용자 지원 이메일: 본인 이메일

   • 개발자 연락처 이메일: 본인 이메일

   • 저장 후 계속.

4. 범위 페이지: 여기서 범위를 추가할 필요 없음 — 서버가 인증 시 요청합니다. 저장 후 계속.

5. 테스트 사용자 페이지: + 사용자 추가를 클릭하고 본인의 Google 이메일을 추가합니다. (본인의 Google 계정). 앱이 '테스트' 상태인 동안 필요합니다. 저장 후 계속.

앱을 게시하거나 Google 확인을 거칠 필요는 없습니다. 테스트 상태 앱은 나열된 테스트 사용자에게 무기한 작동합니다. 테스트 앱의 갱신 토큰은 7일 동안 사용하지 않으면 만료될 수 있습니다. Drive 도구가 인증 오류로 실패하기 시작하면 6단계(npm run auth)를 다시 실행하세요.

4단계 — OAuth 클라이언트 생성 (데스크톱 앱)

1. https://console.cloud.google.com/auth/clients (API 및 서비스 → 사용자 인증 정보)로 이동합니다.

2. + 사용자 인증 정보 만들기 → OAuth 클라이언트 ID.

3. 애플리케이션 유형: 데스크톱 앱. 이름을 desktop-mcp로 지정 → 만들기.

4. 대화상자에서 JSON 다운로드를 클릭합니다.

5단계 — 클라이언트 파일을 서버가 예상하는 위치에 저장

다운로드한 JSON을 정확히 다음 경로/이름으로 저장합니다:

~/.config/google-drive-mcp/gcp-oauth.keys.json

예를 들어 ~/Downloads/client_secret_XXXX.json으로 다운로드된 경우:

mkdir -p ~/.config/google-drive-mcp
mv ~/Downloads/client_secret_*.json ~/.config/google-drive-mcp/gcp-oauth.keys.json

6단계 — 인증 (한 번)

cd ~/mcp-servers/google-drive-mcp
npm run auth

이 명령은 URL을 출력하고 브라우저를 엽니다. 관리하려는 Drive의 Google 계정으로 로그인합니다. 'Google에서 이 앱을 확인하지 않았습니다' 경고가 표시됩니다(앱이 테스트 상태이므로 예상됨) → 고급 → google-drive-mcp(안전하지 않음)로 이동 → 계속 → Drive 권한을 허용합니다.

성공하면 ~/.config/google-drive-mcp/.gdrive-credentials.json에 기록됩니다. (갱신 토큰 — 비공개로 유지하세요. 이미 chmod 600으로 설정되어 있습니다.)

7단계 — 사용

서버는 이미 ~/.claude.json에 google-drive라는 이름으로 등록되어 있습니다. 새 Claude Code 세션을 시작하면 gdrive_* 도구를 사용할 수 있습니다. (MCP 서버는 세션 시작 시 로드되므로 등록 전에 시작된 세션에서는 볼 수 없습니다.)

빠른 수동 스모크 테스트 (선택 사항):

cd ~/mcp-servers/google-drive-mcp && npm start
# prints "google-drive-mcp: connected over stdio", then waits. Ctrl-C to quit.

도구

항목 삭제

gdrive_trash를 사용하는 것이 좋습니다. 되돌릴 수 있으며, Drive는 휴지통 항목을 30일간 보관하고, gdrive_untrash로 원래 위치로 복원할 수 있습니다.

gdrive_delete는 영구적이며 복구할 수 없습니다. 휴지통에 들어가지 않습니다. 항목의 현재 이름과 정확히 일치하는 confirmName이 필요하므로, 삭제 전에 메타데이터를 읽도록 강제하여, 오래되었거나 잘못 입력된 파일 ID가 잘못된 항목을 삭제하는 대신 오류를 발생시킵니다. 폴더를 삭제하면 그 안의 모든 항목이 삭제됩니다.

등록

두 구성 파일에 모두 등록됩니다. 각각 독립적으로 읽히므로, 한 곳에 등록해도 다른 곳에서 서버를 사용할 수 없습니다:

• ~/.claude.json (Claude Code)

• ~/Library/Application Support/Claude/claude_desktop_config.json (데스크톱 / Cowork)

각 파일에 동일한 항목:

"google-drive": {
  "command": "/opt/homebrew/bin/node",
  "args": ["/ABSOLUTE/PATH/TO/mcp-servers/google-drive-mcp/index.js"]
}

node의 절대 경로가 필요하며, 스타일 선택이 아닙니다. Finder에서 또는 로그인 시 실행된 앱은 최소 launchd PATH (/usr/bin:/bin:/usr/sbin:/sbin)를 상속받으며, 여기에는 Homebrew의 /opt/homebrew/bin/node가 전혀 보이지 않습니다. 단순한 "node"는 터미널에서 테스트할 때마다 작동하고 매일 아침 실패합니다. ~/mcp-servers/trello-mcp/doctor.py는 두 구성 파일의 모든 서버를 확인합니다.

나중에 claude CLI를 설치하는 경우, 동등한 명령은 다음과 같습니다:

claude mcp add --scope user google-drive -- /opt/homebrew/bin/node ~/mcp-servers/google-drive-mcp/index.js

파일

• index.js — MCP 서버 (도구 정의)

• auth.js — 일회성 npm run auth 루프백 OAuth 흐름

• lib-auth.js — 공유 OAuth/구성 도우미

• ~/.config/google-drive-mcp/gcp-oauth.keys.json — 사용자가 제공 (5단계)

• ~/.config/google-drive-mcp/.gdrive-credentials.json — npm run auth로 생성

이력서/포트폴리오용

향후 이력서 세션에서 재구성하는 대신 정확한 버전을 유지하기 위해 여기에 보관합니다.

이미 Drive 커넥터가 있는데도 이걸 만든 이유. 기존 커넥터를 대체하는 것이 아니라 확장합니다. 차이는 대량 작업입니다. 프로젝트 중간에 명명 규칙이 변경된 후 수백 개의 파일 이름을 바꾸는 것은 수동으로는 지루하고, 스크립트로는 간단하며, 한 번만 해결하는 것이 아니라 영구적으로 해결할 가치가 있습니다. 이것이 동기가 된 사례입니다.

실제로 한 일: 목표와 제약 조건을 설정했습니다. 한 폴더에 대한 일회성 스크립트가 아니라 모든 미래 프로젝트에서 동일한 시간을 절약해주는 무료 솔루션입니다.

알려진 운영상 주의사항: OAuth 앱의 게시 상태는 갱신 토큰의 수명을 결정합니다. '테스트' 상태에서는 대략 매주 만료됩니다(invalid_grant). 앱을 게시하면 Cloud 프로젝트를 공유하는 모든 통합에 대해 이 제한이 제거됩니다.

포트폴리오 길이 글머리 기호: ~/mcp-servers/trello-mcp/README.md의 공유 버전을 참조하세요. 이 세 가지는 함께 설명하는 것이 가장 좋습니다.

전체 사례 연구: https://zeno-blade-creator.github.io/projects/personal-integrations.html