google-docs-mcp

google-docs-mcp

Google Docs を MCP ツールとして利用できます。Claude や任意の MCP クライアントから、ドキュメントの読み取り、編集、変更提案、コメントができます。

Model Context Protocol を stdio 経由で利用する単一の Go バイナリです。クライアントのサブプロセスとして、ユーザー自身のマシン上で、ユーザー自身の Google アカウントを使って実行されます。ホストするサーバーも、共有デプロイも、サービスアカウントも不要です。Google OAuth クライアントを作成して一度ログインすれば、更新トークンは OS のキーリングに保存されます。

慎重な同僚のようにドキュメントを扱います。適切な粒度で読み取り、周囲の内容を損なわずにその場で編集し、変更を提案として提示し、文章にコメントを付け、表、タブ、ヘッダー、脚注、書式設定にも対応します。

google-docs-mcp を選ぶ理由

既存のサーバーでは、モデルに生の UTF-16 インデックスを渡したり、ドキュメントを気付かないうちに破損させる方法で Markdown を変換したり、インライン表示されない Drive API 経由でコメントのアンカーを設定したりします。このサーバーはインデックス計算をサーバー側で行い、正確なテキストと安定した見出し ID でコンテンツを指定し、最小限の差分で編集し、アンカー付きコンテンツの上書きを拒否します。また、プロジェクトが登録されている場合は Docs API の提案モードを使用します。その根拠と証拠は docs/architecture.md に記載されています。

読み取り、検索、作成、エクスポート、提案モード、直接編集モード、コメントモードでの最小限の差分による編集、書式設定、提案の確認、コメントスレッド、改訂履歴と差分、表、タブ、ヘッダー、フッター、脚注、画像、チップ、名前付き範囲、ページとセクションのレイアウト、名前付きスタイル、gdocs:// リソース、大規模ドキュメントのパフォーマンス、エージェント評価にすべて対応しています。Docs API の Request 共用体に含まれる GA メンバーはすべて出力されます。アーキテクチャドキュメントの §16 には、各ツールで公開するフィールドと、意図的に公開しないフィールドが記載されています。

インストール

go install github.com/mmedum/google-docs-mcp/v3/cmd/google-docs-mcp@latest

これにより、google-docs-mcp が $(go env GOPATH)/bin に配置されます。このパスを MCP クライアントに指定してください。または、最新リリース から署名済みアーカイブ（Linux、macOS、Windows 向け、amd64 および arm64 対応）を取得し、実行する前に検証してください。

tar xzf google-docs-mcp_*_linux_amd64.tar.gz
sha256sum -c checksums.txt --ignore-missing

# The checksum file is signed with a keyless Sigstore certificate tied to
# the release workflow's identity. The bundle carries both.
cosign verify-blob checksums.txt \
  --bundle checksums.txt.bundle \
  --certificate-identity-regexp 'https://github\.com/mmedum/google-docs-mcp/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

# And the archive itself carries build provenance.
gh attestation verify google-docs-mcp_*_linux_amd64.tar.gz --repo mmedum/google-docs-mcp

各アーカイブには SBOM（.sbom.json）も同梱されているため、自分でビルドしていないバイナリの内容を確認できます。go install の場合は、これらは不要です。ビルド前にモジュールプロキシと sum.golang.org がソースを検証します。いずれの場合も、google-docs-mcp --version で、そのバイナリの元となったリリースを確認できます。

Google のセットアップ

各デプロイヤーは、それぞれ独自の Google Cloud プロジェクトと OAuth クライアントを使用します。共有アプリはなく、Google に確認してもらう必要もありません。

1. Google Cloud プロジェクトを新規作成するか、既存のプロジェクトを選択します。

2. Google Docs API と Google Drive API を有効にします （APIs & Services → Library）。

3. OAuth 同意画面を設定します（Google Auth Platform → Audience）。

   • Google Workspace 組織のアカウントを使用する場合は、Internal を選択します。 トークンは有効期限が切れません。
   • 個人アカウントの場合は、公開ステータスを Testing にして External を選択します。自分をテストユーザーとして追加します。このようなアプリの更新トークンは Google によって 7 日後に期限切れになるため、毎週 login を実行します。

4. スコープを追加します（Google Auth Platform → Data Access）：.../auth/documents、 .../auth/documents.readonly、.../auth/drive、.../auth/drive.readonly。

   4 つすべて追加しますが、1 回のログインで要求されるのは最大 2 つです。通常のログインでは documents と drive を要求し、GDOCS_READ_ONLY=true の場合は代わりに documents.readonly と drive.readonly を要求します。同意画面にはクライアントが要求できるスコープが表示されるため、両方を対象にする必要があります。また、付与されていないスコープは、誰かが初めて読み取り専用モードを試した時点で拒否されます。Google は要求されたスコープのみを付与するため、読み取り専用のスコープを追加しても通常のログインには影響しません。

5. OAuth クライアント（Google Auth Platform → Clients）を Desktop app タイプで作成し、その JSON をダウンロードして ~/.config/google-docs-mcp/client_secret.json に保存します（Linux の場合。その他の OS では、OS の設定ディレクトリ内にある google-docs-mcp フォルダーに保存します）。 リポジトリには含めないでください。

6. 次を実行します。

google-docs-mcp login
google-docs-mcp doctor https://docs.google.com/document/d/<some doc you can open>/edit

ドキュメントの指定は任意です。doctor を単独で実行すると、認証情報、スコープ、API への到達可能性を確認し、ドキュメントを指定した場合はそのドキュメントを読み取ります。

google-docs-mcp status --json は、サーバーを起動する前に認証済みかどうかをスクリプトで確認できるよう、同じ状態を 1 つの JSON オブジェクトとして stdout に出力します。分岐には credentials.resolved フィールドを使用します。schema_version が変更されるのは、フィールドが削除される場合、またはその意味が変わる場合のみです。アカウントはテキスト出力と同じように、ドメインのみが表示される形でマスクされます。人間向け出力のラベルはリリースごとに変更されることがありますが、オブジェクトの形式は変わりません。

login はブラウザーを開き、ループバックポートを使用して Google のデスクトップ OAuth フローを完了し、更新トークンを OS のキーリング（Secret Service、Keychain、Credential Manager）に保存します。キーリングを利用できない場合は、警告を表示してアクセス許可を 0600 に設定したファイルに保存します。doctor はすべての手順を確認し、不足しているものを正確に知らせます。

SSH 経由でのログイン

コールバックはリモートホストのループバックアドレスに送信されますが、ブラウザーはローカルで動作するため、ポート転送が必要です。ポートはランダムに割り当てられ、login が出力する URL にのみ、127.0.0.1%3A<port> のようにパーセントエンコードされて表示されます。

google-docs-mcp login --no-browser

URL からポート番号を確認し、2 つ目のローカルターミナルからポートを転送してから、自分のブラウザーで URL を開きます。

ssh -N -L <port>:127.0.0.1:<port> you@remote-host

ssh が bind: Address already in use と表示した場合は、Ctrl-C でログインを中断し、再度開始して別のポートを割り当ててください。--timeout では login の待機時間を設定します。デフォルトは 5 分です。

コメントと提案

提案モード（mode: suggest）、テキスト範囲に固定されたコメント、提案の承認または却下では、Google が 2026-09-30 に一般提供を開始した Docs API の機能を使用します。登録は不要です。Google が特定のドキュメントでこれらの機能を拒否した場合でも、読み取りは引き続き可能です。コメントはテキストに固定する代わりに、そのテキストを引用して Drive 経由で投稿されます。また、提案モードは送信されずに拒否されます。どのような状態かは get_document で確認できます。GDOCS_PREVIEW は非推奨であり、無視されます。

Markdown ファイル

Docs は Drive に保存された Markdown ファイル（.md、text/markdown として指定）を開き、Markdown ファイルのままインプレースで編集します。Docs API はこのようなファイルを読み取れますが、書き込みはすべて拒否します。また、開いているエディターのセッションを通じて書き込むことはできません。書き込み方法はファイル全体をアップロードする方法のみで、アップロードすると開いているエディターが再読み込みされます。そのため、ファイルで作業する方法は 2 通りあります。

一緒にリアルタイムで作業する：作業用コピー。 from_file を指定して create_document を実行すると、そのファイルから Google ドキュメントが作成されます。Google ドキュメントと同じように、あなたと Claude はそのドキュメントで作業できます。編集内容は入力中のテキストと統合され、提案モードでは変更履歴が表示され、コメントは該当箇所に付きます。write_markdown_file は、コピーで変更された部分をブロック単位でファイルに書き戻します。ファイルの残りの部分では、独自の Markdown、フロントマター、Docs が保持しているコメントがそのまま維持されます。コピーの作成後にファイル側でも変更されたブロックへの変更は競合となり、force を指定しない限り拒否されます。force を指定した場合、そのブロックではファイル側のバージョンが維持されます。

ファイルを直接編集する。 get_document は kind: markdown_file を返し、読み取りではファイル独自の Markdown を返します。編集では、呼び出しごとにそのテキストに対する最小限の変更をアップロードします。

• 対象は正確なテキスト、heading_id（get_outline で取得できる next-steps のようなスラッグ）、または heading です。Google ドキュメントでハンドルが使われる箇所では行（L12）を使用し、長い読み取りは行から続きを読み取ります。
• edit_document は insert、append、replace、delete、replace_all を受け付け、内容は指定されたとおりに書き込まれます。書式、表、オブジェクト、レイアウト、タブは拒否されるため、Markdown として記述してください。
• mode: direct はテキストを変更します。mode: comment と add_comment は、エディターが独自のコメントを書き込むのと同じ方法で、アカウント名を付けたコメントをファイルに書き込みます。エディターでは「From imported document」と表示され、保存後も保持されます。ファイルが書き込まれるたびにコメント ID は変わりますが、誰かがエディターでファイルを保存すると変わらなくなります。reply_comment も同じ方法で返信します。ファイルを通じてコメントを解決することはできません（ファイルに書き込まれると、解決によって Google がファイルを読み取れなくなるため）。そのため、エディターで解決してください。Markdown ファイルでは提案を受け付けません。
• Docs がファイル内に保持しているコメントは読み取り結果から除外され、編集で変更されることはありません。また、list_comments では Drive API 経由で作成されたコメントとともに一覧表示されます。コメントのマークアップを含む内容は拒否されます。
• Google ドキュメントと同様に、ガード機能は、コメントが付いたテキスト、画像、脚注参照を変更する直接編集を、強制しない限り拒否します。
• 誰かがファイルを開いている間の書き込み。 Drive にはアップロードを条件付きで実行する方法がなく、開いているエディターには、まだファイルに反映されていない作業が保持されています。書き込みの前に、サーバーはエディターのライブセッションとファイルを比較します。コメント、返信、解決がファイルに反映されていない場合は、少し待ってから拒否します。force を指定していても同様です。その作業はまだどのリビジョンにも含まれていないためです。アップロードの直前にも再度確認します。アップロード後にはファイルの履歴を確認し、その間に誰かが保存していた場合は、その保存内容を維持したうえで、変更をその上に再適用します。
• Docs エディターでファイルを保存すると、Docs はファイル全体を独自の Markdown スタイルで書き換え、フロントマターを見出しに変換します。読み取り時にはフロントマターに関する警告が表示されます。以前のテキストには、list_revisions と revision を指定した read_document でアクセスできます。
• search_documents は kind: markdown_file または any を指定すると Markdown ファイルを検索します。デフォルトでは Google ドキュメントのみが対象です。kind: markdown_file を指定して create_document を実行すると、新しい Markdown ファイルが作成されます。

Word ファイル

Docs は Drive に保存された Word ファイル（.docx）を開いてその場で編集し、Word ファイルのまま保持します。Docs API はファイルを読み取りますが、変更履歴は提案として、コメントはコメントとして扱い、すべての書き込みを拒否します。そのため、このサーバーはファイル自体に書き込みます。get_document は kind: word_file を返し、読み取りは Google ドキュメントと同様に機能し、含まれる要素も処理します。編集はファイルの XML に加えられ、Drive 経由でファイル全体がアップロードされます。

• edit_document は、Google ドキュメントと同じ方法で指定した本文テキストに対して、insert、append、replace、delete、replace_all を受け付けます。replace_all はヘッダー、フッター、脚注にある一致箇所を残し、警告を表示します。段落内で置換されたテキストには最小限の差分のみが適用され、見た目も維持されます。複数段落の内容は段落間に挿入されるか、段落全体が置き換えられます。見出しにはファイル独自の見出しスタイルが適用され、リストは挿入位置のリストを引き継ぎ、レベルは list_level で設定できます。
• mode: suggest は、アカウント名で Word の変更履歴を書き込みます。Docs では提案として、Word では変更履歴として表示されます。mode: direct はテキストを変更します。mode: comment と add_comment は Word のコメントを書き込みます。list_comments でコメントを一覧表示できます。コメントへの返信、解決、削除は Docs エディターで行います。
• 書式設定、表、画像、レイアウト、タブ、提案の確認は拒否され、その旨が通知されます。これらの操作には、ファイルを Google ドキュメントとして保存してください（ファイル > Google ドキュメントとして保存）。
• 保護機能は Google ドキュメントのものと同じです。コメント付きテキスト、提案、画像、脚注参照を削除する直接編集は、強制しない限り拒否されます。
• 誰かがファイルを開いている間の書き込み。 書き込みのたびに、対象となるすべての段落について Docs とファイルの内容が一致しているか確認し、一致しない場合は待機した後に拒否します。アップロードの直前にも再確認し、その後はファイルの履歴を確認します。途中で保存が行われていた場合は、その変更を元に戻し、書き込みを適用しません。ファイルを開いているエディターは再読み込みします。その後、Docs が新しいリビジョンを読み取るまで書き込みを待機します。

クライアントを接続する

Claude Code：

claude mcp add --transport stdio google-docs -- google-docs-mcp

Claude Desktop（claude_desktop_config.json）または Cursor（mcp.json）：

{
  "mcpServers": {
    "google-docs": {
      "command": "/absolute/path/to/google-docs-mcp",
      "env": { "GDOCS_LOG_LEVEL": "info" }
    }
  }
}

Claude Desktop は実行中に claude_desktop_config.json を自身の状態から書き換え、知らない間に行われた編集を削除します。完全に終了してから編集し、その後に起動してください。また、ツール定義は遅延読み込みされるため、チャットでツールを使う前に少し待ってください。

Claude Desktop では、リリースの .mcpb バンドルを開く方法もあります。この場合、編集する設定ファイルは不要です。必要な設定は同じです。OAuth クライアント JSON、記録済みの login を使う場合は空欄のままにできる設定、プロファイル、読み取り専用、デフォルトの書き込みモード、コメントとタブの削除（enable_destructive）、エクスポート先フォルダー（export_dir）です。削除は有効にしない限りオフのままで、バイナリーのエクスポートもフォルダーを選ぶまでオフです。このサーバーは呼び出し前に確認を求めません。Claude Desktop は各ツールの実行を許可し、「1 回許可」または「常に許可」を選べます。「常に許可」したツールは確認なしで実行されるため、必要なツールを使う場合を除き、enable_destructive はオフのままにしてください。このバンドルは両方のアーキテクチャの macOS と Linux、および amd64 バイナリーを使う Windows に対応しています。Windows の arm64 ではエミュレーションで実行されます。バンドルはログインしません。バイナリーもインストールし、google-docs-mcp login を一度実行してください。バンドルは同じ認証情報を使用します。

すべての設定は環境変数です。詳細は docs/configuration.md を参照してください。デフォルト設定を使う場合、何も設定する必要はありません。

ツール

ツール	説明
get_document	タイトル、タブ、リビジョン ID、所有者、最終変更、各種件数、このサーバーの機能（利用可能な書き込みモード、デフォルト）を取得します。タブごとにページ設定、フローティングオブジェクト、名前付き範囲、段落が持つ名前付きスタイル定義も報告します。これらはテキストを読み取るだけでは確認できません。低コストなので、最初に呼び出してください。
get_outline	タブごとの見出しツリーを、安定した heading_id、ブロックハンドル、セクションサイズとともに取得します。
read_document	スコープと予算を指定して、Markdown、プレーンテキスト、または Docs JSON の生データとして読み取ります。heading_id、見出しテキスト、ハンドル範囲、タブ、ヘッダー／フッター／脚注でスコープを指定します。with_handles が false でない限り、ブロックハンドルはテキストとともに取得されます。オプションを指定すると、スタイル、保留中の提案を {++挿入箇所++} ／ {--削除箇所--} ／ {==スタイル変更箇所==} として表示する情報、コメントマーカー {>>c:id<<} が追加されます。
find_in_document	テキストまたは正規表現で検索し、ハンドル、オフセット、コンテキストを返します。
search_documents	タイトルまたはコンテンツ、所有者、変更日でドキュメントを検索します。kind を指定すると Markdown ファイルも対象になります。
export_document	Google 独自の md、txt、html はインラインで出力します。pdf、docx、odt、rtf、epub は GDOCS_EXPORT_DIR 配下に新しいファイルとして出力し、既存ファイルを上書きしません。
create_document	オプションで Markdown コンテンツを指定して新しいドキュメントを作成します。kind: markdown_file は .md ファイルを作成し、from_file はその作業用コピーを作成します。
edit_document	insert、append、replace（最小限の差分）、delete、replace_all（テキストまたは RE2 正規表現）、insert_break、insert_footnote、create_header、create_footer、delete_header、delete_footer、create_named_range、delete_named_range、replace_named_range を一括で実行します。対象には、完全一致するテキスト、heading_id、ハンドル、セル、または後続の編集後も維持される名前付き範囲を指定します。Markdown コンテンツには表や画像を含められます。後続のバッチでテキストが反映された後に、それらを配置します。また、リストを含む場合は、list_level でレベルを指定しない限り、配置先のリスト項目を継続します。mode: suggest、direct、または comment、dry_run、expect_revision、force を指定できます。
format_document	同じ対象、同じモードで text_style、paragraph_style、bullets、clear_formatting を実行します。リンク先には URL、同じタブ内の見出し（get_outline が返す #h.…）、またはタブ（#tab=t.…）を指定できます。Markdown コンテンツでは同じ形式を使用します。
list_suggestions	保留中の編集提案を、ID、テキスト、ハンドルとともに取得します。追加も削除もしない書式設定のみの提案や、各提案のスレッドへの返信も含まれます。
review_suggestion	list_suggestions が示す ID を指定して、提案を承認、却下、または破棄します。
list_comments	すべての返信、解決済み／削除済みの状態、割り当て先、引用テキスト、コメントが付いているブロックを含むコメントスレッドを取得します。
add_comment	範囲にコメントを付ける（その範囲に固定する）か、ドキュメントにコメントします。Markdown ファイルでは、コメントはファイル内に書き込まれます。
reply_comment	スレッドに返信する、解決する、再開する、または自分のコメントや返信を書き換えます。編集提案のスレッドにも返信できます。
list_revisions	リビジョン ID、日時、作成者を含むバージョン履歴を取得します。
diff_revisions	2 つのリビジョン間で、Google の Markdown またはテキストエクスポートの統合差分を取得します。read_document では古い revision 全体を読み取れます。
edit_table	insert_table（データグリッドを指定）、set_cells（セルごとの最小限の差分）、insert_rows、delete_rows、insert_columns、delete_columns、merge_cells、unmerge_cells、style_cells、style_columns（固定幅または均等幅）、style_rows（最小の高さ、改ページの動作）、pin_header_rows を実行します。テキスト編集と同じモードおよびガードを使用します。
insert_object	公開 URL のインライン画像、人物チップ、リッチリンクチップ、または日付チップを指定位置に挿入します。画像のソースをその場で置き換えることも、テキスト範囲に含まれないフローティング画像を含むオブジェクトを削除することもできます。
layout_document	page（サイズ、余白、背景、横向き、ページ番号、先頭ページ／偶数ページのヘッダー、ページレス）、section（1 つのセクションに対する同様の設定と、1～3 列）、section_break、およびタブ全体の NORMAL_TEXT、TITLE、SUBTITLE、HEADING_1 ～ HEADING_6 を再定義する named_style を設定します。
manage_tabs	タブを追加（コンテンツも指定可能）、名前変更、移動、またはネストします。API ではタブの変更を提案できないため、常に直接変更されます。
write_markdown_file	作業用コピーで変更された部分だけを反映して、Markdown ファイルに書き戻します。ファイル側で行われた変更との競合がある場合、強制しない限り書き込みは拒否されます。また、Docs エディターで保存されていない変更を上書きすることはありません。dry_run を指定できます。
追加の 2 つのツールは、GDOCS_ENABLE_DESTRUCTIVE=true の場合にのみ登録されます。
delete_comment（スレッドまたは個別の返信）と delete_tab（コンテンツと
子タブを含むタブ）です。どちらにも破壊的操作の注釈が付いており、各
呼び出しでは confirm_comment_id または confirm_tab に対象を再度指定する
必要があります。delete_comment では、削除対象のテキストが list_comments に
表示されるとおりにどのように始まるかを示す text_start も指定します。これにより、
クライアントのプロンプトで削除対象のコメントが明示されます。サーバーは
コメントを読み取り、内容が異なる場合は [stale] として拒否します。

ドキュメントは、ID、任意の docs.google.com URL、または Markdown ファイルの drive.google.com/file/d/… URL で識別されます。

リソース

コンテキストを MCP リソースとして添付するクライアントは、ツール呼び出しなしで ドキュメントを読み取れます。各リソースは、ハンドル、候補、コメントを含まない Markdown です。読み取りツールは、範囲と予算を指定して読み取るためのものです。

• gdocs://<id> — すべてのタブの本文。400000 文字で切り詰められ、 read_document で続きを読む位置を示すメモが付けられます。
• gdocs://<id>/outline — get_outline が返す見出しツリーです。
• gdocs://<id>/tabs/<tab> — 1 つのタブの本文です。tab には ID、タイトル、または 番号を指定します。

編集対象の指定方法

モデルにインデックス番号が表示されることはありません。対象には、読み取り結果から そのまま引用したテキスト（かぎ括弧、ダッシュ、空白は正規化されます。対象箇所は 1 か所だけに出現する必要があり、複数ある場合は occurrence または within で 区別します）、安定した heading_id で指定するセクション全体、ハンドル（p12）で 指定するブロック（元のリビジョンで有効で、使用時に再確認されます）、表のセル、 または名前付き範囲を指定できます。名前付き範囲は、編集後も有効な唯一のアンカーです。 Google は、その範囲がカバーするテキストに合わせて移動するため、今 create_named_range を実行し、後の呼び出しで target: {named_range: …} を 指定すれば、同じ箇所にアクセスできます。新しいコンテンツは Markdown として 書き込まれます。replace は旧テキストと新テキストの差分が最小になるように適用されるため、 変更されていない単語の書式とアンカー付きコメントは保持されます。

表はハンドル（tbl1）で、セルは r2c3 で指定します。データグリッドを持つ表は 空の状態で挿入し、表ができた後、2 回目のバッチで内容を入力します。表の操作は 順番に読み取られます。ある操作でグリッドが変更された場合、その表に対する後続の操作は 独立したバッチで適用されるため、行、列、セルの番号は、その時点でのグリッドを指します。 過去のリビジョンは Google のエクスポートを通じて読み取り、差分が取られるため、 ハンドルはありません。

安全性

• 読み取りツールには読み取り専用の注釈が付いています。書き込みツールでは、 ユーザーが mode を選択します。suggest（変更履歴付き変更）、direct、 comment（提案をコメントとして投稿し、編集は行いません）です。すべての書き込みは 計画時のリビジョンによって保護されます。並行編集があった場合は 1 回再計画され、 その後は拒否されます。

• 直接編集では、明示的に強制しない限り、コメントアンカー、保留中の提案、画像、 または脚注を含む範囲は削除されません。

• コメントまたはタブを削除する破壊的ツールは、GDOCS_ENABLE_DESTRUCTIVE=true が 設定されていない限り登録されません。GDOCS_READ_ONLY=true を設定すると、 読み取りツールのみが登録され、読み取り専用スコープが要求されます。

• 各呼び出しを承認するのは MCP クライアントです。サーバーから確認を求められることはありません。 claude.ai と Codex は、破壊的操作としてマークされた 2 つの削除について プロンプトを表示します。VS Code は読み取り専用ではないすべてのツールについて、 つまりすべての書き込みと、ローカルファイルに書き込む export_document について プロンプトを表示します。Claude Code では、承認する呼び出しを 1 つずつ 設定の permissions.ask に列挙し、google-docs の代わりにサーバーに付けた名前を 指定してください。たとえば、削除、他のユーザーの提案の確認、Markdown ファイルの 書き戻しは次のとおりです。

  {
    "permissions": {
      "ask": [
        "mcp__google-docs__delete_comment", "mcp__google-docs__delete_tab",
        "mcp__google-docs__review_suggestion", "mcp__google-docs__write_markdown_file"
      ]
    }
  }
  

  GDOCS_REQUIRE_PROMPT は廃止されています。false 以外の値を設定すると、 サーバーは起動しません。誰も監視していない状態で実行するクライアントでは、 GDOCS_ENABLE_DESTRUCTIVE を無効のままにしてください。

• サーバーは Google（googleapis.com と、Google の API が返すリビジョン エクスポートリンク用の docs.google.com）とのみ通信します。テレメトリはありません。 ログ（stderr）にドキュメントのテキストが含まれることはありません。

• 更新トークンは OS のキーリングに保存されます。logout を実行すると、トークンは 失効し、削除されます。

仕組み

MCP client ──stdio──► google-docs-mcp
                       ├── tools     one handler per tool; shapes the reply
                       ├── service   orchestration and scope resolution
                       ├── plan      write planning and all the index math
                       ├── doc       model, handles, sections
                       ├── render    markdown, text, outline
                       ├── gapi      raw REST client for Docs and Drive
                       └── auth      refresh token → access token

インデックス計算がサーバーの外に出ることはありません。モデルは正確なテキスト、heading_id、またはハンドルでコンテンツを指定し、internal/plan がそれを Docs API が必要とする UTF-16 オフセットに変換します。internal/gdocs のワイヤー型はこのプロジェクト独自のもので、生成されたクライアントではなく、ゲートによって Google が公開しているディスカバリードキュメントに準拠しています。

サポートを受ける

google-docs-mcp doctor は認証情報、スコープ、API への到達性を確認し、不足しているものを示します。初回実行時の問題のほとんどは、API が有効になっていないか、自分が追加されていない同意画面が原因です。それでも原因がわからない場合は、イシューを作成してください — バグ報告フォームでは doctor の出力とバージョンを尋ねます。

イシューにドキュメント ID や URL、ドキュメントの内容、client_secret.json、トークンを貼り付けないでください。代わりに、ドキュメントの構造を説明してください。セキュリティ上の問題は、SECURITY.md に従って非公開で報告してください。

バージョン管理

v1.0.0 以降は、通常どおりのセマンティックバージョニングです。ツールの削除や名前変更、必須引数の追加、ツールの返却内容の変更はメジャーバージョンになります。新しいツールと新しい任意引数はマイナーバージョンです。CI のスキーマ差分チェックでこれを徹底しており、すべてのプルリクエストで実行されます。差分に明示されないかぎり、ツールのインターフェースを変更することはできません。

除外項目は一つだけです。これは予想外の変更ではなく、意図的な判断です。ツールのテキスト出力の正確な文言は、モデル向けに書かれており、モデルが誤って読み取った場合には言い換えられます。ツールが返す structuredContent は対象ですが、その周囲の文は対象外です。

各リリースのノートは、CHANGELOG.md の該当セクションにあります。新しいスコープ、追加のログイン、クライアント設定内のコマンド変更など、対応が必要な変更には、そこで Breaking: と記載しています。

開発

make build     # the binary
make test      # race detector, coverage floor
make check     # everything CI runs

make check が完了の基準です。フォーマット、すべてのビルドタグでの go vet、golangci-lint、パッケージごとのカバレッジ下限を設けた競合テスト、govulncheck、ライセンスチェック、シークレットスキャン、API カバレッジゲート、Google API のメソッドやフィールドに判定がない場合に失敗する API フィールドゲート、リリース済みのツールインターフェースとのスキーマ差分チェック、stdio スモークテスト、そして README、ドキュメント、変更履歴がコードと食い違っている場合に失敗する陳腐化チェックが実行されます。

テスト用フィクスチャは合成データです。実際のドキュメントの内容、ID、URLは決して追加しないでください。make bench は大きなドキュメントを扱う処理の性能を測定します。go test -tags=evals ./internal/evals は、自分のアカウントを使ってエージェントの評価を実行します（パッケージコメントを参照してください）。

ドキュメント

• docs/architecture.md — 設計、リクエストの流れ、各規約の根拠となる記録、コントリビューターが覆すべきでない判断について説明します。
• docs/configuration.md — すべての環境変数とフラグを説明します。
• docs/security.md — 脅威モデルについて説明します。ログに記録される内容、doctor が出力する内容、ドライバーが書き込む内容を扱い、各主張はテストで裏付けられています。

貢献

質問やバグ報告はイシューにお寄せください。プルリクエストも歓迎します。CONTRIBUTING.md ではブランチの運用とレビューの流れについて説明しています。make check の成功が必須です。

セキュリティ

SECURITY.md では、報告対象の範囲と、脆弱性を非公開で報告する方法について説明しています。脆弱性について公開イシューを作成しないでください。

行動規範

CODE_OF_CONDUCT.md — Contributor Covenant 3.0。

ライセンス

Apache-2.0 — LICENSE を参照してください。