gdocs — Claude Code용 Google Docs 검토 루프

Claude Code가 Google Doc 및 댓글 스레드를 읽고, 수정 사항을 동일한 Doc의 동일한 URL에 다시 작성할 수 있게 하는 MCP 서버입니다.

리포지토리의 Markdown이 진실의 원천(source of truth)이고 Google Docs는 검토 화면일 뿐인 루프를 위해 만들어졌습니다. 복사-붙여넣기 왕복 작업을 없애줍니다: 초안을 Docs에 붙여넣을 필요도, 리뷰어 코멘트를 터미널에 다시 붙여넣을 필요도 없습니다.

사용자 범위(user scope)로 설치되므로 모든 프로젝트에서 작동합니다.

요구 사항

• Node 18+

• claude CLI

• Google 계정 및 Google Cloud Console에서 약 10분

설치

git clone https://github.com/uma-victor1/gdocs-mcp.git
cd gdocs-mcp
./install.sh

이 명령은 의존성을 설치하고, 서버가 시작되는지 확인하며, Claude Code에 사용자 범위로 등록합니다. 그런 다음 아래 두 가지 자격 증명 단계를 직접 수행하세요.

1. Google Cloud — 1회

1. 프로젝트 생성: https://console.cloud.google.com/projectcreate

2. Google Docs API 및 Google Drive API를 사용 설정합니다(APIs & Services > Library)

3. OAuth 동의 화면: 개인 계정의 경우 사용자 유형 **외부(External)**로 충분합니다. 대상(Audience) 아래에서 자신의 이메일 주소를 테스트 사용자로 추가하세요. 이 단계를 건너뛰는 것이 동의가 실패하는 가장 흔한 원인입니다.

4. 사용자 인증 정보(Credentials) > 사용자 인증 정보 만들기(Create credentials) > OAuth 클라이언트 ID > 데스크톱 앱(Desktop app) > JSON 다운로드

5. ~/.config/gdocs-mcp/credentials.json으로 저장

자격 증명은 의도적으로 저장소 외부에 두므로 git add -A로 커밋될 수 없습니다.

2. 인증 — 1회만

npm run auth

Google은 앱이 인증되지 않았다고 경고합니다. 사용자가 한 명인 앱에서는 예상되는 동작입니다: 고급(Advanced) > (안전하지 않음)...(으)로 이동. 갱신 토큰(refresh token)은 ~/.config/gdocs-mcp/token.json에 모드 0600으로 저장됩니다.

Claude Code를 다시 시작한 후 claude mcp list로 확인하세요.

7일 재인증과 그 이유

동의 화면이 Testing 상태인 동안 Google은 7일마다 갱신 토큰을 만료시킵니다. 이는 테스트 중인 외부 앱의 문서화된 동작이며, 버그가 아니고, 이 범위 모음으로는 우회할 방법이 없습니다: auth/drive은 제한(restricted) 범위이며, 제한 범위로 프로덕션에 게시하려면 CASA 보안 평가가 필요하기 때문입니다 — 1인용 도구에는 그만한 가치가 없습니다.

따라서 대략 일주일에 한 번 도구 호출이 "Authorisation expired" 오류와 함께 실패합니다. 해결법:

npm run auth

15초면 충분합니다. Google Workspace 계정이 있다면 완전히 피할 수 있습니다: 해당 조직 아래에 Cloud 프로젝트를 만들고 동의 화면 사용자 유형을 **내부(Internal)**로 지정하세요. 내부 앱은 7일 만료도 테스트 사용자 목록도없습니다.

도구

모든 도구는 Doc URL 또는 fileId를 받습니다.

댓글 앵커 트레이드오프

Google은 각 댓글을 텍스트의 구간(span)에 앵커합니다. 그 구간을 다시 쓰면 스레드는 떨어져나가거나 자동으로 해결됩니다. 따라서:

• 작은 수정 → replace_text. 앵커가 유지되며 리뷰어의 맥락이 보존됩니다.

• 구조적 재작성 → push_markdown. 빠르지만 스레드 손실이 예상됩니다. 이전에 존재하던 열린 스레드 수를 보고하므로, 손상이 조용히 아니라 보이게 처리됩니다.

• 변경보다 추가 → append_text. 항상 끝에만 삽입하므로 기존의 구간이 움직이지 않고 앵커가 깨지지 않습니다.

• 재작성 전에 답글을 달 수 있습니다. reply_comment는 무엇이 왜 변경되었는지 기록을 남깁니다.

왜 기존 서버가 아닌 이 서버인가

Docs OAuth 토큰을 보유한 MCP 서버는 계정의 모든 문서를 읽고 재작성할 수 있습니다. Google이나 Anthropic의 공식 Docs MCP 서버는 존재하지 않습니다; 게시된 어떤 것은 전부 개인 발행자의 제3자 패키지입니다. 이것은 약 250줄의 Anthropic MCP SDK와 Google 자체 클라이언트 라이브러리입니다 — 신뢰하기 전에 읽어볼 수 있을 만큼 작습니다.

읽기 전용 모드

claude mcp remove gdocs -s user
claude mcp add gdocs -s user -e GDOCS_MCP_READONLY=1 -- node "$PWD/server.mjs"

읽기는 계속 작동하고, 모든 쓰기 도구는 거부합니다. 다른 사람이 문서를 소유할 때 유용합니다.

문제 해결

언제든 npm run smoke로 서버를 독립적으로 검증하세요.

Claude Code를 통하지 않고 단일 도구를 실행하려면:

node call.mjs read_comments '{"doc":"https://docs.google.com/document/d/FILEID/edit"}'

사용 권한 취소

https://myaccount.google.com/permissions에서 권한을 취소한 후, ~/.config/gdocs-mcp/token.json을 삭제하세요.

구조

server.mjs         the nine tools
google.mjs         auth + Drive/Docs clients; credential paths
auth.mjs           one-time interactive OAuth   (npm run auth)
smoke.mjs          starts the server, lists tools  (npm run smoke)
call.mjs           invoke one tool from the shell, for debugging
install.sh         deps, verify, register at user scope
docs/guide.html    the setup walkthrough as a standalone page

라이선스

MIT. LICENSE 참조.