Google Drive MCP Server

Claude Code 세션에서 Google Sheets, Slides 및 Drive를 읽고/쓰기 위한 로컬 Python MCP 서버입니다.

작동 방식

서버는 GCP의 OAuth 2.0 Desktop App을 사용합니다. 첫 사용 시 동의 절차를 위해 브라우저가 열립니다. 승인하면 로컬에 token.json이 저장됩니다. 이후 실행에서는 토큰을 재사용하며, 만료되면 브라우저를 다시 열지 않고 자동으로 갱신합니다.

인증 파일:

Related MCP server: google-workspace-mcp-with-script

초기 설정 (첫 번째)

1. GCP 자격 증명

1. GCP Console → APIs & Services → Credentials에 접속합니다.

2. OAuth 2.0 Client ID를 생성합니다 (유형: Desktop App).

3. JSON을 다운로드하여 이 폴더에 credentials.json으로 저장합니다.

4. GCP 프로젝트에서 API를 활성화합니다:

   • Google Sheets API

   • Google Slides API

   • Google Drive API

2. 의존성 설치

Windows (PowerShell):

cd "C:\Users\<usuario>\Documents\MCP_Servers\googleDrive"
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

macOS / Linux:

cd ~/Documents/MCP_Servers/googleDrive
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. 첫 번째 로그인 (OAuth)

브라우저를 열고 승인하려면 수동으로 실행하세요:

Windows:

.venv\Scripts\activate
python main.py

macOS / Linux:

source .venv/bin/activate
python main.py

브라우저에서 승인하면 token.json이 생성되고 서버가 시작됩니다. Ctrl+C로 종료할 수 있습니다 — 토큰은 다음 사용을 위해 저장됩니다.

Claude Code에 등록

MCP 서버를 등록하는 방법은 두 가지입니다:

옵션 A — 프로젝트별 (.mcp.json)

프로젝트 루트에 .mcp.json 파일을 생성합니다. MCP는 해당 프로젝트에서만 활성화됩니다.

Windows:

{
  "mcpServers": {
    "google-drive": {
      "type": "stdio",
      "command": "C:\\Users\\<usuario>\\Documents\\MCP_Servers\\googleDrive\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\<usuario>\\Documents\\MCP_Servers\\googleDrive\\main.py"
      ]
    }
  }
}

macOS / Linux:

{
  "mcpServers": {
    "google-drive": {
      "type": "stdio",
      "command": "/Users/<usuario>/Documents/MCP_Servers/googleDrive/.venv/bin/python",
      "args": [
        "/Users/<usuario>/Documents/MCP_Servers/googleDrive/main.py"
      ]
    }
  }
}

옵션 B — 사용자 전역 (~/.claude/settings.json)

MCP를 Claude Code 전역 설정에 추가합니다 — 모든 프로젝트에서 사용할 수 있습니다.

~/.claude/settings.json을 편집하고 (Windows: C:\Users\<usuario>\.claude\settings.json) mcpServers 키를 추가하세요:

Windows:

{
  "mcpServers": {
    "google-drive": {
      "type": "stdio",
      "command": "C:\\Users\\<usuario>\\Documents\\MCP_Servers\\googleDrive\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\<usuario>\\Documents\\MCP_Servers\\googleDrive\\main.py"
      ]
    }
  }
}

macOS / Linux:

{
  "mcpServers": {
    "google-drive": {
      "type": "stdio",
      "command": "/Users/<usuario>/Documents/MCP_Servers/googleDrive/.venv/bin/python",
      "args": [
        "/Users/<usuario>/Documents/MCP_Servers/googleDrive/main.py"
      ]
    }
  }
}

MCP가 특정 프로젝트 전용일 때는 옵션 A를 사용하세요. 어떤 프로젝트에서든 접근하려면 옵션 B를 사용하세요.

환경 변수 (선택 사항)

기본적으로 서버는 자신의 폴더에서 credentials.json 및 token.json을 찾습니다. 경로를 변경하려면 .env.example을 기반으로 .env를 생성하세요:

GOOGLE_CREDENTIALS_PATH=credentials.json
GOOGLE_TOKEN_PATH=token.json

사용 가능한 도구 (17개 도구)

Google Sheets (7)

Google Slides (7)

Google Drive (3)

모든 도구는 직접 ID 또는 전체 Google URL을 허용합니다:

• 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms

• https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms/edit

문제 해결

invalid_grant / 자동으로 갱신되지 않고 만료된 토큰

token.json을 삭제하고 python main.py를 다시 실행하여 OAuth 흐름을 다시 수행하세요.

Windows:

Remove-Item ".\token.json"
python main.py

macOS / Linux:

rm token.json
python main.py

API가 활성화되지 않음

GCP Console에서 세 가지 API가 활성화되어 있는지 확인하세요: Google Sheets API, Google Slides API, Google Drive API.

Claude Code에 MCP가 표시되지 않음

Python 실행 파일 경로가 올바른지 확인하세요:

• Windows: .venv\Scripts\python.exe

• macOS/Linux: .venv/bin/python

.mcp.json 또는 settings.json에는 절대 경로를 사용하세요 — 상대 경로는 작동하지 않습니다.