title: "Google Drive MCP Server" date: 2026-08-19 tags:

• 프로젝트/workspace

• 하위프로젝트/tools

• 유형/guide

• 영역/tech

• 날짜/2026-08-19

Google Drive MCP Server

Cursor, Claude Code 및 Claude Desktop용 로컬 MCP 서버입니다. 이 서버를 통해 에이전트는 Google Drive에서 파일을 검색하고 읽으며, Google Docs와 Google Sheets를 생성하고 수정합니다.

Google Docs는 읽을 때 Markdown으로 변환되고, 스프레드시트는 CSV, 프레젠테이션은 텍스트로 변환됩니다. Docs는 세밀하게 수정할 수 있습니다: 삽입, 교체, 스타일, 제목, 목록, 이름 변경, 복제. Sheets는 값, 형식, 탭, 행과 열을 다룰 수 있습니다. 개인 Drive와 Shared drives 모두에서 작동합니다.

저장소: https://github.com/Stillfrozen/gdrive-mcp
wagnerlabs/gdrive-mcp 기반.

OAuth 키는 사용자 디스크에만 저장됩니다. git에는 포함되지 않습니다.

Google Cloud 단계별 설치 (프로젝트, API, Desktop OAuth, test users): docs/INSTALL.ru.md

빠른 시작

Node.js 18+ (가급적 20)과 작업할 Drive가 있는 Google 계정이 필요합니다.

git clone https://github.com/Stillfrozen/gdrive-mcp.git
cd gdrive-mcp
./scripts/install.sh

스크립트가 의존성을 설치하고, 프로젝트를 빌드하며, Google Cloud 설정을 안내합니다: 프로젝트, API, 동의 화면, Desktop 클라이언트, 브라우저 로그인. 마지막에 MCP 클라이언트용 완성된 코드 조각을 출력합니다.

변경 없이 단계만 보기:

./scripts/install.sh --dry-run

Console에서 직접 클릭하고 싶다면 — docs/INSTALL.ru.md에 모든 화면 설명이 있습니다.

Cursor

~/.cursor/mcp.json (또는 프로젝트의 .cursor/mcp.json)에서 — 절대 경로만 사용:

{
  "mcpServers": {
    "gdrive": {
      "command": "node",
      "args": ["/absolute/path/to/gdrive-mcp/dist/index.js"],
      "env": {
        "GDRIVE_OAUTH_PATH": "/absolute/path/to/gdrive-mcp/credentials/gcp-oauth.keys.json",
        "GDRIVE_CREDENTIALS_PATH": "/absolute/path/to/gdrive-mcp/credentials/.gdrive-server-credentials.json"
      }
    }
  }
}

JSON이 저장소의 credentials/에 있다면 env 블록은 필수가 아닙니다. 파일에 이미 다른 서버가 있다면 나머지를 덮어쓰지 말고 mcpServers 안에 "gdrive"를 추가하세요.

그 다음 Cursor → Settings → MCP → Reload. gdrive 표시등이 녹색이 되어야 합니다.

Claude Code CLI

claude mcp add --scope user gdrive -- node /absolute/path/to/gdrive-mcp/dist/index.js

--scope user는 서버를 전역으로 설정합니다. 제거: claude mcp remove gdrive.

Claude Desktop

claude_desktop_config.json에서:

{
  "mcpServers": {
    "gdrive": {
      "command": "node",
      "args": ["/absolute/path/to/gdrive-mcp/dist/index.js"]
    }
  }
}

Related MCP server: Google Drive MCP Server

도구

읽기

쓰기: Sheets

쓰기: Docs

셀에 값 쓰는 방법

gdrive_update_sheet 및 gdrive_append_sheet의 value_input_option 매개변수:

• USER_ENTERED (기본값) — Sheets UI에서 입력하는 것과 동일. =SUM(A1:A10) 수식이 실행되고, 숫자와 날짜가 형식화됩니다.

• RAW — 그대로. =SUM(A1:A10) 문자열은 텍스트로 유지됩니다.

파일 읽는 방법

gdrive_read_file은 Workspace 문서를 자동으로 내보냅니다:

전체 스프레드시트(탭, 구조, 쓰기)는 gdrive_read_file이 아닌 gdrive_get_spreadsheet_info와 Sheets write-tools를 통해 가져오세요.

Doc의 문단, 제목, 목록 및 앵커 편집은 gdrive_get_document_info를 사용하세요. 응답에는 원시 text와 문단 끝 줄바꿈이 없는 displayText가 있습니다. displayText가 일반적으로 앵커로 더 안전합니다. Markdown은 gdrive_read_file이 가장 빠르게 제공합니다.

보안 모델

여러 계층: MCP 주석, "먼저 읽기", Docs에는 추가로 개정 및 앵커, Sheets에는 현재 값 검증.

1. 도구 주석

각 tool은 MCP annotations을 선언합니다. 클라이언트는 파괴적인 작업 전에 확인을 요청할 수 있습니다. 위 표의 Destructive / Idempotent 열을 참조하세요.

2. 먼저 읽기, 그 다음 쓰기

서버는 에이전트가 이 세션에서 이미 열었던 스프레드시트와 Docs를 기억합니다.

스프레드시트는 다음 후에 읽은 것으로 간주됩니다:

• gdrive_read_file (셀을 CSV로)

• gdrive_get_spreadsheet_info (구조 및 탭)

• gdrive_create_sheet (에이전트가 방금 파일을 직접 생성)

Doc은 다음 후에 읽은 것으로 간주됩니다:

• gdrive_read_file (Markdown + Google이 제공한 경우 개정)

• gdrive_get_document_info (탭 또는 구조화된 텍스트)

• gdrive_create_doc

이 단계 없이 쓰기는 거부됩니다:

You must read this spreadsheet before writing to it…

You must read this document before writing to it…

이렇게 하면 에이전트가 잘못된 파일을 대상으로 지정할 가능성이 줄어듭니다. 목록은 프로세스 재시작 시 초기화됩니다 (각 MCP 세션은 새로 시작).

gdrive_get_file은 여기에 포함되지 않습니다: Drive 메타데이터일 뿐, 내용이 아닙니다.

3. 개정을 고려한 Docs 쓰기

편집은 에이전트가 마지막으로 읽은 개정에 바인딩됩니다:

• conflict_mode: "strict" (기본값) — Docs requiredRevisionId. 문서가 그 사이에 변경되면 쓰기가 실패합니다.

• conflict_mode: "merge" — Docs targetRevisionId. Google은 가능하면 다른 편집과 병합합니다.

구조화된 내용 캐시는 gdrive_get_document_info include_content=true 이후 세션에 유지됩니다. 앵커 도구(gdrive_insert_doc_text, gdrive_replace_doc_text, gdrive_update_doc_paragraph_style, gdrive_update_doc_list)는 개정이 동일한 동안 이를 사용합니다. 그렇지 않으면 서버가 스냅샷을 다시 캡처합니다.

정확한 텍스트 교체를 위해 expected_text를 전달할 수 있습니다: 전송 전에 서버가 해당 범위에 정확히 그 문자열이 있는지 확인합니다.

앵커 기반 gdrive_delete_doc_text 및 gdrive_replace_doc_text의 경우, 일치 항목이 탭 끝에 닿으면 서버가 문단의 마지막 줄바꿈만 자동으로 제거합니다. Docs API는 세그먼트의 종료 newline이 있는 범위를 삭제하지 않습니다. 명시적 start_index / end_index는 이 작업을 수행하지 않습니다: 끝 newline은 직접 제외해야 합니다.

4. Sheets 사전 조건

gdrive_update_sheet에는 선택적 expected_current_values — values와 동일한 형태의 2차원 배열이 있습니다. 서버가 셀을 읽고 비교합니다. 일치하지 않으면 쓰기가 거부되고 오류에 실제 내용이 포함됩니다.

• 정밀 편집 (단일 셀, 수식) — expected_current_values를 전달하세요.

• 대량 작업 (수천 행) — 전달하지 마세요. 그렇지 않으면 요청이 두 배가 되어 할당량에 도달합니다.

include_previous_values: true는 감사용으로 이전 값을 반환합니다. expected_current_values가 설정된 경우 이전 값은 항상 반환됩니다.

롤백

Docs 및 Sheets 편집은 Google Workspace 버전 기록에 표시됩니다. 거기서 롤백할 수 있습니다.

어떤 tool도 Drive에서 파일 전체를 삭제하지 않습니다. 파괴적인 작업은 Doc 내부와 스프레드시트 내부에서만 발생합니다. 파일 삭제는 Drive UI에서만 가능합니다.

구성

키 경로는 환경 변수로 재정의할 수 있습니다:

업데이트

git pull 후 upgrade를 실행하세요. 프로젝트를 다시 빌드하고, setup-manifest.json에 새 API 또는 scope가 있으면 auth를 다시 수행하도록 요청합니다:

cd /path/to/gdrive-mcp
git pull
./scripts/upgrade.sh

매니페스트가 변경되지 않았다면 스크립트는 다시 빌드하고 최신 상태라고 알려줍니다. Cursor는 MCP Reload 후 dist/를 인식합니다. 서버를 다시 등록할 필요는 없습니다.

scope 정보: 서버는 좁은 drive.file이 아닌 전체 drive를 요청합니다. 이는 Google의 최소 권장 사항보다 넓지만, 그렇지 않으면 임의의 접근 가능한 파일을 읽고 기존 Docs에 쓸 수 없습니다 (rename, duplicate, 편집). documents scope는 구조화된 읽기와 batchUpdate에 필요합니다.

Testing 상태의 External 애플리케이션에서 refresh token 수명은 7일입니다. 이후 invalid_grant가 발생하고 다시 npm run auth를 실행해야 합니다. 자세한 내용 및 옵션 (Internal / Publish) — docs/INSTALL.ru.md에 있습니다.

제한 사항

• gdrive_create_sheet는 스프레드시트를 Drive 루트에 생성합니다. 폴더를 선택할 수 없습니다.

• Sheets용 gdrive_read_file은 첫 번째 탭의 CSV만 반환합니다. 나머지 탭은 gdrive_get_spreadsheet_info를 통해 접근합니다.

• Docs용 gdrive_read_file은 항상 Markdown입니다. 탭, 문단 경계, 목록, 앵커는 gdrive_get_document_info를 사용합니다.

• Doc의 형식과 구조를 변경하기 전에 먼저 gdrive_get_document_info include_content=true를 읽으세요.

• gdrive_replace_all_doc_text는 기본적으로 첫 번째 탭만 처리합니다. 모든 탭을 처리하려면 명시적으로 all_tabs: true를 사용해야 합니다.

개발

npm install
npm run dev          # tsx, без сборки
npm run build
npm test
npm run test:live    # живой Google Doc, нужны сохранённые credentials
npm run test:watch

npm run test:live는 임시 Doc을 생성하고, MCP와 동일한 스트림을 통해 텍스트를 삽입한 다음, gdrive_get_document_info로 확인하고 마지막에 파일을 휴지통에 넣습니다.

라이선스

MIT