gdocs-comments-mcp

gdocs-comments-mcp

Google Docs のインラインコメントをテキスト範囲に固定 — Google API では実行できない唯一のコメント操作です。

_{クイックスタート  ·  対象範囲  ·  ツール  ·  設定  ·  仕組み  ·  トラブルシューティング  ·  サーバーへのデプロイ  ·  よくある質問}

Google Docs を中心に AI プロセスを構築しているとします。下書きをレビューしたり、契約書を監査したり、編集上のフィードバックを提供したりするエージェントです。そのフィードバックを届ける自然な方法は、人間が行うのと同じ方法です。つまり、文書の末尾やチャットに大量のテキストを貼り付けるのではなく、対象となる文に正確に固定されたコメントです。

しかし、ここで行き詰まります。Google API ではアンカー付きコメントを作成できません。 Docs API にはコメント用のエンドポイントがなく、Drive API は anchor フィールドを受け付けるものの、Docs エディタはこれを無視します。そのため、コメントは文書全体に対する一般的なコメントとして表示されます。

この MCP サーバーは、そのギャップを埋めます。エージェントがテキストの断片とコメントを指定して add_comment を呼び出すと、サーバーは実際にログインした Google Docs セッションを通じて投稿するため、まるで人間がテキストを選択して Ctrl+Alt+M を押したかのように、コメントがそのテキストに正確に固定されます。

公式 API を使わない理由

このサーバーが行うことは一つだけです。Google ドキュメントにコメントを追加することです。 特に重要なのは、特定のテキスト範囲に固定されたアンカー付きコメントです。これを実行できる Google API はありません。

Docs API にはコメント用のエンドポイントがありません。Drive API の comments.create は anchor フィールドを受け付けますが、Docs エディタはこれを無視するため、コメントはアンカーなしの文書全体に対するコメントとして表示されます。エディタ独自のアンカー形式（kix.*）は非公開で、外部から生成することはできません（Drive API ドキュメント、issuetracker #292610078、2016 年から未解決）。エディタ UI を操作する方法しかないため、このサーバーはまさにそれだけを行い、それ以外は何もしません。（コメントの一覧表示、返信、解決、削除はすでに Drive API で実行できます。これらには Drive ベースのツールを使用してください。）

できること — できないこと

このサーバーが意図的に行うのは、範囲を絞った一つの処理だけです。組み込む前にお読みください。

✅ できること： Google ドキュメントにコメントを追加します。特定のテキスト範囲に固定する方法（API では実現できない処理）と、ドキュメント全体に固定しない方法があります。

❌ できないこと：

重要： このツールはドキュメントの内容を一切返しません。設計上、出力は構造化データのみ（{ ok, anchored, occurrence_used, verified }）です。これにより、悪意のあるドキュメントがエージェントに指示を注入するのを防ぎます。そのため、エージェントは内容を確認せずに書き込みます。ドキュメントを適切にレビューするには、読み取り機能（Docs API の documents.get）と組み合わせ、引用する正確なテキストを find_text に渡してください。認証方式はそれぞれ異なります。このサーバーはログイン済みのブラウザーセッションを操作し（OAuth は不要）、Docs／Drive API には OAuth トークンまたはサービスアカウントが必要です。ただし、どちらも同じ Google アカウントで利用できます。

クイックスタート

コマンドを一つ実行するだけです。ログインすると（ブラウザーが一度開きます）、Claude Code にサーバーが登録されます。

npx -y gdocs-comments-mcp setup

これで完了です。下の使い方に進んでください。手動で設定したい場合や、別のクライアントを使う場合は、以下の手順を参照してください。

npx -y gdocs-comments-mcp login

# Claude Code
claude mcp add gdocs-comments -- npx -y gdocs-comments-mcp

{
  "mcpServers": {
    "gdocs-comments": {
      "command": "npx",
      "args": ["-y", "gdocs-comments-mcp"]
    }
  }
}

{
  "mcpServers": {
    "gdocs-comments": {
      "command": "npx",
      "args": ["-y", "gdocs-comments-mcp"]
    }
  }
}

{
  "mcpServers": {
    "gdocs-comments": {
      "command": "npx",
      "args": ["-y", "gdocs-comments-mcp"]
    }
  }
}

{
  "servers": {
    "gdocs-comments": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "gdocs-comments-mcp"]
    }
  }
}

3. 使う — エージェントに次のように依頼します。

https://docs.google.com/document/d/1AbC…/edit にコメントを追加してください。「quarterly numbers」に固定して、「金曜日までに更新してください」と記載してください。

エージェントは add_comment を呼び出し、次の結果を受け取ります。

{ "ok": true, "anchored": true, "occurrence_used": 1, "verified": true }

…コメントがドキュメント内のハイライトされた語句に、ログインしたアカウントから追加されます。

Playwright ブラウザーのダウンロードは不要です。デフォルトでは、このサーバーは playwright-core を使用して、インストール済みの Google Chrome を操作します。

ツール

add_comment

戻り値は { ok, anchored, occurrence_used, verified } です。verified: true は、送信後に投稿されたコメントがページ上で確認されたことを意味します。find_text が指定されているのに見つからない場合、呼び出しは TEXT_NOT_FOUND で失敗し、何も投稿されません。

このツールはドキュメントの内容を一切返さないため、悪意のあるドキュメントがこのツールを通じてエージェントに指示を注入することはできません。

check_connection

Google セッションを確認し、{ connected, mode } を返します。connected: false の場合は、再度 npx gdocs-comments-mcp login を実行してください。

**対象範囲に関する注意：**このサーバーが行うのは、アンカー付きコメントの作成だけです。コメントの一覧表示、返信、解決、削除はすべて Drive API（comments.*）で問題なく行えます。こちらのほうが高速で、ブラウザーも不要です。これらの操作には Drive ベースの MCP を使用してください。

CLI

npx gdocs-comments-mcp login    # one-time interactive Google sign-in
npx gdocs-comments-mcp status   # is the saved session still valid?
npx gdocs-comments-mcp logout   # delete the saved session/profile

設定

すべて任意の環境変数で設定できます。

トラブルシューティング

新しいマシンで初めて実行しますか？npx gdocs-comments-mcp status を実行すると、現在の状態が正確にわかります。

サーバー／データセンターの IP での実行

一般家庭の回線を使うマシンでは、デフォルトのプロファイルモードがそのまま動作します。データセンターの IP では、Google の不正利用防止機能により、保存済みセッションを再利用する新規起動のブラウザープロセスが拒否され、accounts.google.com/confirmidentifier にリダイレクトされます。プロファイルから再起動しても動作しません。

動作する方法は、オペレーターがログインしたブラウザーそのものを起動したままにし、このサーバーから接続することです。

1. 長時間実行する Chrome／Chromium を --remote-debugging-port=9333 を指定して起動し（ヘッドレスの場合は Xvfb 上で起動）、そのブラウザー内で一度 Google にログインします。
2. GDOCS_COMMENTS_CDP_URL=http://127.0.0.1:9333 を指定して MCP サーバーを実行します。

サーバーは CDP 経由でその稼働中のセッションを操作し、独自のブラウザーを起動することはありません。数時間おきに docs.google.com へ移動してセッションを維持してください。アイドル状態が続くと、約 1～2 週間でセッションの有効期限が切れます。

仕組み

API ではコメントのアンカーを指定できないため、このサーバーは人が行うのとまったく同じように、実際の Google ドキュメントエディターを操作します。add_comment 呼び出しの一連の流れを説明します。

1. ログイン済みのブラウザーに接続します。 デフォルトの プロファイルモード では、サーバーが永続的な Chromium プロファイル（playwright-core 経由でインストール済みの Google Chrome を使用します。ブラウザーの追加ダウンロードは不要です）を管理します。gdocs-comments-mcp login を使って一度ログインすると、Google のセッション Cookie が ~/.gdocs-comments-mcp/profile に保存され、以降の実行時にヘッドレスで再利用されます。CDP モード（GDOCS_COMMENTS_CDP_URL）では、サーバーは代わりに Chrome DevTools Protocol 経由で、起動したままにしておくブラウザーに接続します。サーバーのデプロイを参照してください。

2. ドキュメントを開きます。 https://docs.google.com/document/d/<id>/edit?hl=en に移動します。まず doc ID が検証され、移動先は docs.google.com に厳密に制限されるため、ツールが別の場所へ誘導されることはありません。ページが accounts.google.com に移動した場合、セッションは無効になっており、呼び出しは SESSION_EXPIRED を返します。次のステップで検索バーのカウンターを解析できるよう、?hl=en によって UI の言語を固定します。

3. アンカーテキストを検索します。 ドキュメント本文は選択可能な DOM ではなく HTML の <canvas> に描画されるため、テキストを検索してクリックすることはできません。その代わり、処理全体をキーボード操作で行います（これにより、ロケールや CSS クラスにも依存しません）。

Ctrl/Cmd+F  →  type find_text  →  read the "N of M" match counter

コメントを追加する前にカウンターを読み取ることが、安全性を確保するうえで重要です。find_text に一致するものがない場合や、occurrence が一致数を超えている場合、呼び出しは TEXT_NOT_FOUND で失敗し、何も投稿されません。カーソルがたまたま置かれていた場所に、キー操作だけでコメントが気付かれないまま追加されるという従来の失敗を防ぎます。

4. 指定された出現箇所を選択してコメントします。 N 番目の一致箇所に移動するために Enter を N 回押し、Esc で検索バーを閉じます（その出現箇所の選択状態は維持されます）。続いて、次の操作を行います。

Ctrl/Cmd+Alt+M  →  type comment_text  →  Ctrl/Cmd+Enter (submit)

Ctrl/Cmd+Alt+M は「現在の選択範囲にコメントを挿入」する Docs のショートカットです。API では作成できない、まさにそのアンカー付きコメントを作成します。キーボードショートカットはプラットフォームに応じて選択されます（macOS では Cmd、それ以外では Ctrl）。

（find_text を省略すると、ステップ 3～4 は「ドキュメントの先頭にカーソルを置いて、そこにコメントする」という処理にまとめられます。これは一般的なアンカーなしのコメントです。）

5. 検証して結果を返します。 コメントを送信した後、サーバーはコメントのテキストがページに表示されるまで待機し、{ ok, anchored, occurrence_used, verified } を返します。verified: true は、投稿されたコメントが実際に確認されたことを意味します。ドキュメントの内容が返されることはないため、悪意のあるドキュメントからエージェントに指示を紛れ込ませることはできません。同じウィンドウでキーボード操作を行うと処理が交錯して互いを壊すため、同時に行われる呼び出しはミューテックスで直列化されます。

add_comment ─▶ attach browser ─▶ open doc (?hl=en) ─▶ Ctrl/Cmd+F find_text
             ─▶ check match counter ─(0 matches)─▶ TEXT_NOT_FOUND, nothing posted
             ─▶ Enter×N ─▶ Esc ─▶ Ctrl/Cmd+Alt+M ─▶ type ─▶ Ctrl/Cmd+Enter
             ─▶ verify comment in page ─▶ { ok, occurrence_used, verified }

制限事項

• UI の自動操作は、API よりも本質的に安定性に欠けます。 Google がエディターを作り変えると、更新されるまで動作しなくなる可能性があります。verified フラグで、コメントが投稿後に実際に確認されたかどうかがわかります。UI の変更に関する報告を歓迎します。
• ログイン中のアカウントには、対象ドキュメントへのコメント権限が必要です。
• find_text は単一行のテキストでなければなりません（検索バーは 1 行です）。また、ドキュメント内のテキストと完全に一致する必要があります。
• 使用されていないセッションは、約 1～2 週間で期限切れになります。status で状態を確認し、login で解決できます。
• 呼び出しは直列化されるため、一括コメント追加は仕様上、逐次処理になります（通常、コメントごとに数秒かかります）。
• Google の通常の UI を通じて自分の Google アカウントを自動操作する場合、Google の利用規約を遵守する責任は利用者にあります。自分のアカウントを使用してください。スパムには使用しないでください。

セキュリティ

AI エージェント（および MCP クライアント）に見えるもの。 機密情報は何もありません。サインインは実際のブラウザーで行い、Google の認証情報は Google に直接入力します。login の手順はターミナルの CLI であり、MCP ツールではないため、モデルがこの処理に関与することはなく、パスワード、2FA、Cookie、OAuth トークンを目にすることもありません。通常の使用時に add_comment および check_connection ツールが返すのは構造化されたステータスのみ（{ ok, anchored, occurrence_used, verified } / { connected, mode }）で、ドキュメントの内容は一切返しません。そのため、悪意のあるドキュメントがこのツールを通じてモデルに指示を紛れ込ませることはできません。モデルのコンテキストに届くのは、エージェント自身が提供した情報（doc、find_text、comment_text）と、場合によってはエラーメッセージ内のローカルファイルパスのみです。

機密情報の実際の保存場所。 Google セッション Cookieは、0700 のアクセス権で作成されるプロファイルディレクトリ（~/.gdocs-comments-mcp/profile）に保存されます。このディレクトリはパスワードと同様に扱ってください。ディスク上に保存され、モデルに返されることはありません。logout を実行すると削除されます。また、Google デバイスのアクティビティからサーバー側で失効させることもできます。オプションの監査ログに保存されるのはハッシュのみで、内容は保存されません。残るリスクは、一般的なローカルマシンのセキュリティ管理です。ディレクトリへの読み取りアクセス権を持つ別のプロセスがセッションを再利用できる可能性がありますが、これは MCP のデータフローではなく、通常のローカルセキュリティの問題です。

封じ込め。 ドキュメント ID は厳密に検証され、ナビゲーション先は docs.google.com に固定されています。そのため、ツールをほかのサイトへ誘導することはできません。

よくある質問

Google Docs API または Drive API で、特定のテキスト範囲にアンカー付きコメントを作成できますか？ いいえ。Google Docs API にはコメント用のエンドポイントがなく、Drive API の comments.create は anchor フィールドを受け付けますが、Docs エディターはこれを無視します。その結果、コメントはアンカーなしのドキュメント全体に対するコメントとして表示されます。このプロジェクトは、まさにこの問題を回避するために存在します。公式 API を使わない理由をご覧ください。

Google Docs にインラインコメント／アンカー付きコメントをプログラムから追加するには？ この MCP サーバーを使うか、このサーバーと同じ方法を使ってください。REST API を呼び出すのではなく、Docs エディターの UI を操作して（テキストを検索し、Ctrl+Alt+M を押して）コメントを追加します。仕組みで一連の処理を詳しく説明しています。

AI エージェント（Claude、Cursor、Copilot）から Google Docs にコメントできるようにするには？ このサーバーを MCP クライアントに追加すると（クイックスタート）、エージェントは実際のアンカー付きコメントを投稿する add_comment ツールを使えるようになります。AI によるドキュメントレビュー、契約書や編集内容へのフィードバック、自動校正のワークフローに最適です。

Google Cloud プロジェクト、OAuth クライアント、またはサービスアカウントが必要ですか？ いいえ。通常の Google アカウントを使ったブラウザーでの初回の対話型ログイン（gdocs-comments-mcp login）だけで認証できます。API 認証情報、OAuth 同意画面、サービスアカウントの設定は不要です。

Google Workspace、共有ドライブ、コメント投稿者のみのアクセス権でも使えますか？ はい。ログイン中のアカウントに、そのドキュメントへのコメント権限以上があれば使えます。

サーバーまたは CI で実行できますか？ はい。サーバー／データセンター IP での実行をご覧ください。データセンター IP では、ブラウザーを再起動する代わりに、ログイン状態を維持したブラウザーに CDP 経由で接続します。

コントリビューション

Issue と PR を歓迎します。特に、キーボード操作のフローを妨げる Docs UI の変更に関する報告をお待ちしています（お使いのロケールと、verified が false だったかどうかを記載してください）。シンプルな ESM で、ビルド手順はありません。git clone、npm install、node src/cli.js を実行してください。

ライセンス

MIT © Stanisław Herjan

_{キーワード： Google Docs のアンカー付きコメント · Google Docs API のインラインコメント · Google Docs へのプログラムによるコメント追加 · Google Docs コメント API の回避策 · Google Docs 用 MCP サーバー · Model Context Protocol · Claude / Cursor / Copilot と Google Docs の連携 · AI によるドキュメントレビュー · Playwright による Google Docs の自動化 · Google Docs のテキスト範囲へのコメント。}