gdrive-write-mcp

AI 어시스턴트에게 Google Drive에 대한 실제 쓰기 액세스를 제공하는 MCP 서버 — 파일의 ID, 공유 설정, 댓글, 버전 기록을 보존하는 제자리 콘텐츠 업데이트, 추가, 찾기/바꾸기 편집을 제공합니다.

문제

대부분의 AI 어시스턴트용 Google Drive 통합은 읽기 및 생성만 가능합니다. 파일을 검색하고, 읽고, 새로 만들고, 오래된 파일을 휴지통으로 옮길 수는 있지만, 이미 존재하는 파일의 콘텐츠를 변경할 방법은 없습니다.

작은 결함처럼 들리겠지만, 결코 작지 않습니다. 제자리 쓰기가 없으면 "이 문서 편집"은 다음과 같이 됩니다:

1. 파일을 읽습니다.

2. 수정된 콘텐츠로 새 파일을 만듭니다.

3. 이전 파일을 휴지통에 버립니다.

결과물에는 기술적으로 올바른 텍스트가 들어 있지만, 그 외의 모든 것이 잘못되었습니다:

gdrive-write-mcp는 그 공백을 메웁니다. Google Drive API는 항상 제자리 콘텐츠 업데이트를 지원해 왔으며, 이것은 그 기능을 MCP로 노출하는 작고 집중된 서버입니다.

Related MCP server: Google Docs MCP Server

기능

편집

• replace_in_file — 정확히 일치하는 찾기 및 바꾸기. 기본으로 사용해야 하는 도구: 전체 문서를 다시 보낼 필요가 없고, 언급되지 않은 콘텐츠를 실수로 삭제할 일도 없습니다.

• append_to_file / prepend_to_file — 양쪽 끝에 추가합니다. 이미 있는 내용을 다시 보낼 필요 없습니다. 로그, 일기, 변경 로그에 적합합니다.

• update_file_content — 전체 문서를 교체합니다. 본질적으로 파괴적이므로, 기본값이 아닌 최후의 수단으로 모델에 문서화되어 있습니다.

읽기

• read_file — 콘텐츠와 다음 쓰기를 안전하게 만드는 데 사용되는 revisionToken을 반환합니다.

• get_file_metadata — 파일을 다운로드하지 않고 이동 여부를 확인합니다.

• search_files — Drive 쿼리 구문을 지원하므로 파일 이름을 쓰기 도구에 필요한 ID로 변환할 수 있습니다.

• list_revisions — 제자리 편집이 보존하는 버전 기록입니다.

생성

• create_file — 진짜 새 문서를 만들 때 사용하며, 선택적으로 네이티브 Google Doc 또는 Sheet로 변환할 수 있습니다.

제대로 처리하는 두 가지

1. 동시 편집은 조용히 무시되지 않고 거부됩니다

순진한 쓰기 도구의 실패 방식은 조용하고 대가가 큽니다. 문서를 읽고 30초 동안 생각한 뒤 다시 쓰면, 그 사이 동료가 추가한 문단을 덮어씁니다. 아무도 오류를 받지 못하고, 며칠 후에 그 문단이 없다는 것을 발견하기 전까지 아무도 눈치채지 못합니다.

여기의 모든 읽기는 revisionToken을 반환하고, 모든 쓰기는 이를 받습니다:

read_file(fileId)                    → revisionToken: "0B1a2…"
update_file_content(fileId, content, expectedRevisionToken: "0B1a2…")

파일이 변경된 경우 쓰기는 단순한 409 대신 모델에게 정확히 무엇을 해야 하는지 — 다시 읽고, 다시 적용하고, 다시 쓰기 — 알려주는 오류와 함께 거부됩니다. 대상 지정 도구(replace_in_file, append_to_file, prepend_to_file)는 단일 호출 안에서 읽기와 쓰기를 수행하므로 보호 기능을 자동으로 포함하며, 토큰을 직접 처리할 필요가 없습니다.

Drive는 실제 바이너리 콘텐츠가 있는 파일에만 headRevisionId를 노출합니다. Google 네이티브 Docs와 Sheets에는 이 값이 없는데, 바로 그 파일들이 브라우저 탭에서 열려 있는 파일이므로 동시 인간 편집이 가장 일어나기 쉬운 곳입니다. 이러한 파일에는 토큰이 modifiedTime으로 대체되므로 네이티브 파일도 보호됩니다.

2. 네이티브 Google 파일은 정직하게 처리됩니다

Drive는 매우 다른 두 종류의 것을 저장하며, 이 둘을 혼동하는 것은 Drive 통합에서 가장 흔한 버그 원인입니다:

• 업로드된 파일 (text/markdown, application/pdf, …) — 바이트 입력, 바이트 출력.

• 네이티브 편집기 파일 (application/vnd.google-apps.document, …) — 자체 바이트가 없습니다. 구체적인 형식으로 내보내기 하여 읽고, Drive가 수집 시 다시 변환하는 형식을 업로드하여 씁니다.

이 서버는 어떤 유형인지 감지하여 그에 맞게 라우팅합니다. Docs는 일반 텍스트가 아닌 markdown으로 내보내집니다. 이는 읽기-수정-쓰기 왕복 과정에서 문서를 조용히 평문으로 평탄화하지 않고 제목, 목록, 강조를 보존하기 위해서입니다. 바이너리 파일은 UTF-8로 디코딩되지 않고 base64로 인코딩되므로 PDF가 텍스트 도구를 거치면서 손상될 수 없습니다.

설치

git clone https://github.com/anaborne/gdrive-write-mcp.git
cd gdrive-write-mcp
npm install
npm run build

Node 18 이상이 필요합니다.

설정

1단계 — Google OAuth 클라이언트 만들기

1. Google Cloud Console을 열고 프로젝트를 만들거나(기존 프로젝트 선택 가능) 선택합니다.

2. Google Drive API를 사용 설정합니다: APIs & Services → Library → Google Drive API → Enable.

3. OAuth 동의 화면을 구성합니다: APIs & Services → OAuth consent screen. External을 선택하고 필수 항목을 입력한 다음 Test users 아래에 자신의 Google 계정을 추가합니다. (앱이 "Testing" 상태인 동안에는 목록에 있는 테스트 사용자만 인증할 수 있습니다 — 개인 도구에는 바로 그 상태가 적합합니다.)

4. 사용자 인증 정보를 만듭니다: APIs & Services → Credentials → Create Credentials → OAuth client ID → Desktop app.

5. Client ID와 Client secret을 복사합니다.

2단계 — 리프레시 토큰 가져오기

cp .env.example .env
# put GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in .env
npm run authorize

이 과정은 http://localhost:4181에서 일회성 동의 흐름을 열고 리프레시 토큰을 출력합니다. 이를 .env에 추가합니다:

GOOGLE_CLIENT_ID=1234567890-abcdef.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-…
GOOGLE_REFRESH_TOKEN=1//0g…

3단계 — MCP 클라이언트를 서버에 연결하기

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "gdrive-write": {
      "command": "node",
      "args": ["/absolute/path/to/gdrive-write-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "…",
        "GOOGLE_CLIENT_SECRET": "…",
        "GOOGLE_REFRESH_TOKEN": "…"
      }
    }
  }
}

Claude Code:

claude mcp add gdrive-write \
  --env GOOGLE_CLIENT_ID=… \
  --env GOOGLE_CLIENT_SECRET=… \
  --env GOOGLE_REFRESH_TOKEN=… \
  -- node /absolute/path/to/gdrive-write-mcp/dist/index.js

그 외 — 서버는 stdio를 통해 MCP를 사용합니다. 세 가지 환경 변수를 설정한 상태에서 node dist/index.js를 하위 프로세스로 실행합니다.

4단계 — 작동 확인하기

npm run verify

이 명령은 실제 Drive에 대해 종단 간 검사를 실행합니다. MCP 클라이언트와 동일한 방식으로 서버를 시작하고, 공식 MCP 클라이언트로 stdio를 통해 서버를 구동하며, 이 프로젝트가 주장하는 동작을 검증합니다 — 오래된 쓰기가 거부되는지, 거부된 쓰기가 파일을 그대로 두는지, 모든 편집 후 파일 ID가 변경되지 않는지, 네이티브 Google Doc이 읽기-편집-읽기 왕복 후에도 Doc으로 유지되는지 등.

Drive에 임시 파일 두 개를 만들고, 중간에 실패하는 경우를 포함해 완료되면 휴지통으로 옮깁니다. 녹색 요약 줄이 표시됩니다:

✓ ALL 41 CHECKS PASSED — the server works against live Drive.

실패한 항목이 있으면 출력에서 특정 검사를 지정하고 어떤 결과가 반환되었는지 보여줍니다. 충돌 및 네이티브 Doc 검사에는 특정 실패가 의미하는 바를 설명하는 추가 진단 정보가 포함됩니다. 예를 들어 백슬래시로 이스케이프된 #은 콘텐츠가 markdown이 아닌 일반 텍스트로 가져와졌음을 의미합니다.

이것은 형식적인 절차가 아닙니다. 단위 테스트 스위트가 49개 테스트에서 모두 통과하고 CI도 통과했지만, 실제 결함이 코드에 남아 있었습니다. markdown에서 네이티브 Doc을 만들면 # Heading이라는 리터럴 문자를 포함하는 Doc이 조용히 생성되었습니다. 목(mock)이 구현과 동일한 잘못된 가정을 포함하고 있었기 때문에 실제 실행에서만 발견되었습니다. drive.ts 또는 mime.ts를 변경한 후에는 이 명령을 실행하십시오.

도구 참조

read_file

콘텐츠와 revisionToken, mimeType, modifiedTime을 반환합니다. 네이티브 파일은 내보내집니다(Docs → markdown, Sheets → CSV, Slides → 일반 텍스트). 바이너리 파일은 base64로 인코딩되어 반환됩니다.

replace_in_file

일치는 리터럴이며 정규식이 아닙니다. 검색 텍스트의 . 또는 $1은 말 그대로 해당 문자를 의미합니다. oldString이 두 번 이상 나타나고 replaceAll이 false이면 호출은 추측하지 않고 실패합니다. 조용히 잘못된 항목을 편집하는 것은 아무도 잡아내지 못하는 버그이기 때문입니다.

append_to_file / prepend_to_file

반복된 추가는 균일하게 구분됩니다 — 이어지는 줄이나 점점 넓어지는 빈 줄 간격이 생기지 않습니다.

update_file_content

모든 것을 교체합니다. expectedRevisionToken이 없으면 마지막으로 파일을 읽은 후 발생한 변경 사항을 덮어씁니다.

create_file

search_files

name contains 'budget'
fullText contains 'quarterly review'
'FOLDER_ID' in parents
mimeType = 'application/vnd.google-apps.document'

get_file_metadata / list_revisions

둘 다 fileId를 받습니다. list_revisions는 선택적 pageSize도 받습니다.

보안

전체 Drive 범위를 사용하는 이유. 이 서버는 기본적으로 https://www.googleapis.com/auth/drive를 요청합니다. 더 좁은 drive.file 범위는 앱 자체가 만든 파일에만 접근을 허용하므로, 이미 보유한 문서를 편집하는 것이 전부인 도구에는 사용할 수 없습니다. 이는 실제 트레이드오프이며, 숨기지 않고 명확히 밝힙니다. 토큰은 인증된 계정의 Drive에 있는 모든 것을 읽고 쓸 수 있습니다.

워크플로가 어시스턴트가 직접 만든 파일만 다루는 경우, authorize 단계와 서버 모두에서 더 좁은 범위를 대신 요청하세요:

GOOGLE_OAUTH_SCOPE=drive.file

둘은 일치해야 합니다. 리프레시 토큰은 부여된 범위를 그대로 지니므로, 한쪽에서 토큰을 발급하고 다른 쪽에서 서버를 실행하면 호출 시점에 혼란스러운 403 오류가 발생합니다. 서버는 파일별 범위가 활성화된 경우 시작 시 stderr에 경고를 출력하므로, 다른 사람의 문서에서 나중에 404가 발생해도 미스터리가 아닙니다.

범위를 제한하는 방법:

• 전용 Google 계정을 인증하고, 접근 가능하게 하려는 특정 파일이나 폴더만 공유하세요.

• OAuth 앱을 Testing 모드로 유지하여 나열된 테스트 사용자만 인증할 수 있게 하세요.

• 언제든지 myaccount.google.com/permissions에서 접근 권한을 취소하세요.

리프레시 토큰 처리. 이는 Drive의 비밀번호입니다. 자체적으로 만료되지 않습니다. .env(여기서는 git-ignored) 또는 MCP 클라이언트 설정에 보관하고, 커밋된 파일에는 절대 넣지 마세요. 유출된 경우 위 링크에서 취소하면 즉시 무효화됩니다.

원격 측정 없음. 이 서버는 Google API에만 네트워크 호출을 하며, 다른 곳으로는 하지 않습니다.

문제 해결

Error 403: access_denied

Google은 이 코드가 실행되기 전에 동의 화면을 거부하고 있습니다. auth/drive는 제한된(restricted) 범위입니다 — Google의 가장 엄격한 등급 — 그리고 제한된 범위는 앱이 이를 허용하도록 구성되지 않으면 차단됩니다. Google Auth Platform에서 다음 순서로 확인하세요:

1. **Audience → 게시 상태가 "Testing"**이어야 하며, "In production"이 아니어야 합니다. 프로덕션의 미검증 앱은 작성자 자신을 포함해 누구에게도 제한된 범위를 사용할 수 없습니다. Testing 모드에서는 검증 없이 최대 100명의 나열된 테스트 사용자에게 허용됩니다.

2. Audience → Test users에 로그인하는 정확한 계정이 포함되어 있어야 합니다.

3. Branding → 앱 이름, 사용자 지원 이메일, 개발자 연락처 이메일이 모두 저장되어 있어야 합니다. 불완전한 동의 화면은 유효하지 않은 화면입니다.

변경 사항이 반영되는 데 몇 분이 걸립니다. 편집 직후에도 여전히 실패하면 5분을 기다렸다가 다시 시도하세요.

이를 완전히 우회하려면 차단되지 않는 비제한 파일별 범위를 요청하세요:

GOOGLE_OAUTH_SCOPE=drive.file npm run authorize

npm run verify가 다루는 모든 파일은 서버가 직접 만든 것이므로, 전체 검증 스위트는 drive.file에서 통과합니다 — 동의 화면 구성이 정리되는 동안 서버가 작동하는지 확인하는 데 유용합니다. 다른 곳에서 만든 문서에는 도달하지 못하므로, 영구적인 경로가 아니라 진단 경로입니다.

개발

npm install
npm run build       # compile TypeScript to dist/
npm test            # build, then run the unit suite (no network, no credentials)
npm run verify      # end-to-end check against a real Drive account
npm run typecheck   # type-check without emitting
npm run watch       # rebuild on change

npm test와 npm run verify는 서로 다른 질문에 답합니다. 단위 테스트 스위트는 Drive API를 모킹합니다. 로직이 올바른지 증명하고, CI에서 실행되며, 자격 증명이 필요 없습니다. npm run verify는 통합이 올바른지 증명합니다 — Google이 이 서버가 가정하는 방식, 특히 네이티브 파일 변환과 리비전 토큰 관련 동작을 실제로 수행하는지 확인합니다. drive.ts 또는 mime.ts의 변경은 둘 다로 확인해야 합니다.

코드는 문서를 조용히 손상시킬 수 있는 부분이 네트워크에 닿지 않고 테스트 가능하도록 구성되어 있습니다:

src/
  index.ts    entry point; stdio transport
  auth.ts     OAuth client from environment
  drive.ts    Drive operations, incl. the concurrency guard
  edits.ts    pure text transforms — no I/O, fully unit-tested
  mime.ts     native vs. binary vs. textual classification
  tools.ts    MCP tool definitions and handlers
  errors.ts   error types written to be actionable by a model

스위트는 찾기/바꾸기 경계 사례(정규식처럼 보이는 리터럴, 교체 문자열의 $&, 여러 줄 대상, 모호한 일치), 추가/앞에 삽입 시임 로직, MIME 분류, 동시성 가드 — 충돌하는 쓰기가 절대 API에 도달하지 않는 것을 포함 — 를 다룹니다.

기여

이슈와 풀 리퀘스트를 환영합니다. 어떤 규모의 변경이든 먼저 이슈를 열어 작업 전에 접근 방식을 합의해 주세요.

도구를 추가하는 경우 순수 로직에 대한 테스트를 추가하고, 이를 읽을 모델을 위해 설명을 작성하세요 — 단지 무엇을 하는지가 아니라 이웃 도구보다 언제 사용해야 하는지를 말하세요.

라이선스

MIT — LICENSE 참조.