gdocs — Claude Code 用 Google Docs レビューループ

Claude Code が Google ドキュメントとそのコメントスレッドを読み、修正内容を同じ URL の同じドキュメントに書き戻せるようにする MCP サーバーです。

リポジトリ内の Markdown が正本（source of truth）で、Google Docs はレビュー面にしか使われない、というループのために作られました。コピー＆ペーストの往復が不要になります。下書きを Docs に貼り付けることも、レビュアーのコメントをターミナルに貼り直すこともありません。

ユーザースコープでインストールされるため、すべてのプロジェクトで動作します。

必要条件

• 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 へのユーザースコープ登録が行われます。その後、以下の 2 つの資格情報設定ステップを自分で行ってください。

1. Google Cloud（一度だけ）

1. プロジェクトを作成: https://console.cloud.google.com/projectcreate

2. Google Docs API と Google Drive API を有効にする（API とサービス > ライブラリ）

3. OAuth 同意画面: ユーザータイプは外部で、個人アカウントなら問題ありません。Audience 内で、自分のアドレスをテストユーザーとして追加してください。これを省略すると、同意が失敗する最も一般的な原因になります。

4. 認証情報 > 認証情報を作成 > OAuth クライアント ID > デスクトップ アプリ > JSON をダウンロード

5. ~/.config/gdocs-mcp/credentials.json として保存

この資格情報は意図的にリポジトリ外に配置され、git add -A では絶対にコミットされません。

2. 認証（一度だけ）

npm run auth

Google はアプリが未認証だと警告します。ユーザーが 1 人だけのアプリでは想定通りです。詳細 > ... へ移動（安全ではない） が該当します。リフレッシュトークンは ~/.config/gdocs-mcp/token.json に、パーミッション 0600 で保存されます。

Claude Code を再起動し、claude mcp list で確認してください。

7日ごとの再認証と、その理由

同意画面がテスト状態にある間、Google はリフレッシュトークンを 7 日ごとに失効させます。これはテスト中にある外部アプリの既知の仕様であり、バグではありません。このスコープ構成でも回避できません。auth/drive は制限付き スコープであり、制限付きスコープで本番公開するには CASA セキュリティ評価が必要です。一人用ツールとしては割に合いません。

そのため、おおかた 1 週間に 1 回程度、ツール呼び出しが「認証の有効期限が切れました」"Authorisation expired" で失敗します。対処は次の通りです:

npm run auth

約15秒です。Google Workspace アカウントがあれば問題を完全に回避できます。その組織配下に Cloud プロジェクトを作成し、同意画面のユーザータイプを 内部 に設定してください。内部アプリには 7 日間の失効期限がなく、テストユーザーリストも必要ありません。

ツール

すべてのツールはドキュメント URL または fileId 単体を受け付けます。

コメントアンカーのトレードオフ

Google は各コメントをテキストの一部に固定（アンカー）します。その範囲を書き換えると、スレッドは切り離されるか自動的に解決されます。つまり:

• 小さな修正 → replace_text。 アンカーは残り、レビュー時刻は文脈を維持できます。

• 構造的な書き直し → push_markdown。 高速ですが、スレッドの消失は避けられません。実行前にオープン中のスレッド数が報告されるため、ダメージが黙って発生することではなく、見える形になります。

• 変更ではなく追記 → append_text。 常に末尾に挿入するだけなので、既存の部分が移動せず、アンコールも壊れません。

• 書き直す前に返信を残す。 reply_comment が、何が変更されたのかとその理由と理由の記録を残します。

既製サーバーではなくこれを使う理由

Docs の OAuth トークンを保持する MCP サーバーは、アカウント内のすべてのドキュメントを読み取って書き換刃できます。しかし Google や Anthropic による公式の Docs MCP は存在しません。公開されているものは、個人の出版社からのサ。 すべてサードパーティです。これは、Anthropic の MCP SDK と Google 純正クライアントライブラリによる約 250 行のコードで、信頼する前に読み込むのに十分な大きさです。

読み取り専用モード

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 経由せずツールを 1 つだけテストするには:

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

アクセス取り消し

https://myaccount.google.com/permissions からアクセ, secretsを取り消し、~/.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 を参照してください。