gdocs-mcp

@dasasian/gdocs-mcp

AI エージェント（Claude Code など）がGoogle ドキュメントをローカルファイルのように扱えるMCP サーバーです。読み取り、コンテンツによる編集、提案の確認と解決、コメントの管理、タブや複数の Google アカウントをまたいだ操作ができます。

**ステータス：**ベータ版です。ツール群は完成しており、すべての変更は単体テストだけでなく、実際の API に対して検証されています。まだレンダリングできないのは Markdown のコードブロックだけです（ロードマップを参照）。

これを開発した理由

多くの Google ドキュメント MCP サーバーは、ドキュメントを平坦なテキストとして扱います。このサーバーは、他のどこにもない機能を補います。

• 操作できる差分としての提案。 list_suggestions は保留中の変更履歴を 変更前 → 変更後 として表示し、apply_suggestions は1件以上をきれいに承認／却下します。read_doc では <ins>/<del> としてインライン表示できます。
• ファイルのような編集。 edit_doc はローカルの Edit のように、一意に特定できるテキストを検索して書き換えます。インデックスが表に出ることはありません。
• コメント。 スレッド（作成者、引用文、返信、解決済みの状態）の読み取り、返信、解決、追加ができます。
• サブファイルとしてのタブ。 ドキュメントはタブのフォルダーです。drive ls <doc> で一覧表示し、drive mv で名前の変更、並べ替え、ネストができます。
• 複数のアカウント。 複数の Google アカウントを認証し、プロジェクトごとにデフォルトを選択できます。

どんなことを頼めるか

ツールを呼び出す必要はありません。自然な言葉で頼めば、エージェントがツールを実行します。

テンプレートを作り直さずに記入する

「Proposal Template を /Clients/Acme にコピーして、『Acme Q3 Proposal』という名前にし、クライアント名、日付、料金表を入力して。」

コピーにはレターヘッド、正確なサイズのロゴ、フォント、ページ設定など、Markdown との往復変換では再現できないものがすべて維持されます。そのうえで、変更する箇所だけを編集します。すでにあるドキュメントをもう一度入力する必要はありません。

ひとつの指示でレビューを一通り実施する

「保留中の提案を差分で表示して、誤字の修正を承認し、意味を変えるものは却下してから、未解決のコメントに返信し、対応が済んだものを解決して。」

4つのツールを一文で使い、あなたが助けを必要としている判断も途中で行えます。多くの Google ドキュメント連携では、変更履歴を確認することすらできず、安全に操作することはなおさら困難です。

**その他：**Markdown のフォルダーを Drive のツリーとして公開する、多数のドキュメントのスタイルのばらつきを監査する、画像を含むドキュメントをリポジトリに戻す → docs/recipes.md。

インストール

npm install -g @dasasian/gdocs-mcp

ソースからインストールする場合：

git clone https://github.com/dasasian/gdocs-mcp && cd gdocs-mcp
npm install && npm run build
npm link   # makes `gdocs-mcp` available globally, same as the published package

その後、インストール済みユーザーとまったく同じ手順で、以下のセットアップを行ってください。（npm link はビルド先の gdocs-mcp バイナリへのシンボリックリンクを作成します。開発ワークフローについては CONTRIBUTING.md を参照してください。）

セットアップ

Google Cloud OAuth クライアントが必要です（初回のみ）。ユーザーがそれぞれ自分のクライアントを作成します。これにより認証情報を自分で管理でき、制限付きの Drive スコープに関する Google アプリの審査も不要になります。

1. プロジェクトを作成して API を有効化します（またはセットアップガイドを利用してください）。

   gcloud projects create my-gdocs-mcp
   gcloud config set project my-gdocs-mcp
   gcloud services enable docs.googleapis.com drive.googleapis.com
   

2. OAuth 同意画面（Cloud Console → APIs & Services → OAuth consent screen）：ユーザーの種類を External にして、自分を Test user に追加します。長期間有効なトークンを使う場合は、公開ステータスを In production に設定します（リフレッシュトークンの有効期限が 7 日になるのを防げます）。
3. OAuth クライアント → 認証情報を作成 → OAuth client ID → Desktop app。JSON をダウンロードし、~/.config/gdocs-mcp/client_secret.json として保存します。
4. アカウントを認証します（ブラウザーが開きます）。

   gdocs-mcp add-account
   

   使用する Google アカウントごとに繰り返します。

MCP クライアントを設定する

プロジェクトの .mcp.json（Claude Code）または同等のファイルに、次のように記述します。

{
  "mcpServers": {
    "gdocs": {
      "command": "gdocs-mcp",
      "env": { "GDOCS_DEFAULT_ACCOUNT": "[email protected]" }
    }
  }
}

GDOCS_DEFAULT_ACCOUNT は、このプロジェクトでデフォルトとして使う認証済みアカウントを指定します。これにより、仕事用のプロジェクトと個人用のプロジェクトで、再認証せずに別々のアカウントを指定できます。どのツール呼び出しでも、account 引数を指定して上書きできます。

すべてのプロジェクトで利用できるようにしたい場合は、ユーザースコープで一度だけ登録します：claude mcp add gdocs -s user -e [email protected] -- gdocs-mcp。その後、プロジェクトで .gdocs-mcp.json を使って、アカウントと新規ドキュメントのデフォルト folder を個別に設定できます。

{ "account": "[email protected]", "folder": "https://drive.google.com/drive/folders/…" }

write_doc はパス（/Reports/Q3 Report）を指定した場合にのみ作成します。名前だけ（Q3 Report）を指定した場合は作成せず、デフォルトフォルダーにドキュメントを保存することをユーザーに伝えるようエージェントに指示し、呼び出しに使う完全なパスを返します。マイドライブの最上位に新しいドキュメント（/Q3 Report）を作成する場合も、同様に一度拒否されます。そこに作成したい場合は、同じ呼び出しをもう一度行うと作成されます。デフォルトフォルダーのパスは write_doc の説明にも含まれており、サーバー起動時に読み込まれます。デフォルトフォルダーがない場合は、フォルダーを指定するよう案内します（~/Q3 Report）。解決順序の詳細はdocs/setup.mdを参照してください。

ファイルを手作業で編集する必要はありません。エージェントに 「このプロジェクトのデフォルトアカウントを [email protected] にして」 または 「ここでは Manuscripts フォルダーをデフォルトにして」 と伝えるだけで、必要に応じてフォルダー名で検索し、set_project_default を使って .gdocs-mcp.json を作成してくれます。

ツール

以下の表はリファレンスです。実際に何を依頼できるかについては、上記の依頼できることまたは**docs/recipes.mdの全項目を参照してください。 | ツール | 説明 | |---|---| | read_doc | Markdown とインライン HTML として読み取ります。冒頭に <style> ブロック（名前付きスタイルを CSS として記述：p、h1～h6、.title、.subtitle）が付きます。段落には、ルールと異なる場合に限り style="…" が表示されます（配置、間隔、行の高さ、インデント）。テキストの色・サイズ・フォントは <span style="…"> として返されるため、スタイルが確認でき、往復変換も可能です。モード：clean・tracked（<ins>/<del>）・accepted・rejected。segment：body（デフォルト）／header／footer／all。本文を読み取ると、ヘッダー／フッターに含まれる内容も必ず報告されるため、レターヘッドが空として読み取られることはありません。マークアップとして解析されるテキストはリテラルとして示されます。例：<p>4. Term</p>、5 \* 3、実際のバックスラッシュを表す \\。スペースまたはタブで始まる、または終わる行は <p>⇥Indented clause</p> として読み取られ、書き込み時には <p> 内のすべてのスペースとタブが保持されるため、読み取った内容を書き戻すと同じ文書になります。改ページは単独行の <div style="page-break-after:always"></div> として読み取られ、書き戻すと改ページになります | | edit_doc | 一意なテキストスニペットを置き換えます（文字列をアンカーとして使用し、マークアップの違いは許容します。新しいテキストではインライン Markdown と、read_doc に表示される CSS を使用できます）。マークアップが異なる同じ単語を編集する場合は、スタイルのみの編集となり、削除や挿入は行われません。<style> ブロック内のルールを編集すると、1 回の updateNamedStyle ですべての文書のスタイルが変更されます。改ページは独立した行なので、new_string に Title page\n<div style="page-break-after:always"></div> を指定すると、次の段落が新しいページに配置され、アンカーはその行をまたぐことができます | | get_page_setup / set_page_setup | 文書全体のページ設定を読み取り／設定します。余白、ページサイズ（プリセットまたは明示指定）、向き（ファイル ＞ ページ設定） | | write_doc | ローカルの Write と同様に書き込みます。何も指定されていないパスは作成されます。フォルダー内の文書（/Work/Contract）、文書内のタブ（/Work/Contract/Notes）、子タブ（/Work/Contract/Part 2/Ch.4）が作成され、確認を求められることはありません。既存のものを指すパスは置き換え**られます。最初の呼び出しは、段落、コメント、提案、タブ位置、人物／日付／リンクのチップ、ブックマークへのリンク、セクション区切り、段組み区切りの損失概要と confirmLoss 文字列を返して拒否されます。ユーザーに伝え、その文字列を指定して再度呼び出すと置き換えられます（文字列にはリビジョンと件数が含まれます）。その間に文書が変更されていた場合は、再度拒否されます。Markdown を使用します（read_doc に表示されるものと同じ CSS：<style> ブロック、<p style>、<span style>。未対応のプロパティがある場合、何も送信される前に書き込みに失敗します。改ページは単独行の <div style="page-break-after:always"></div> です。また、<hr style="page-break-before:always">、break-before: page、break-after: page も使用できますが、その他の <div> や <hr> は拒否されます）。長いテキストには contentFile を使用します。images { src, objectId } を返します | | insert_content | 指定位置に新しい Markdown コンテンツを挿入します。at: "end"（デフォルト）／"top"／一意なアンカーを指定します。edit_doc でアンカーにできるものがない、文書末尾がテーブルの場合に、その後へ段落を追加する方法です。write_doc と同様に改ページ行を指定できます | | export_doc | 文書をローカルファイルにエクスポートします。形式は pdf（デフォルト）、docx、odt、rtf、txt、html、epub、md（Google によるサーバーサイドでのレンダリング）です。文書パスを指定するとすべてのタブがエクスポートされます。タブパス（/Work/Contract/Ch.4）を指定すると、非公開でレート制限のある Google エンドポイントを通じてそのタブのみ（子タブを除く）がエクスポートされます。失敗した場合は対象を拡大せず、拒否されます | | list_suggestions | 保留中の提案を before → after の差分として表示します。segment でヘッダー／フッターの提案を読み取れます | | apply_suggestions | 1 つ以上の提案をまとめて承認または却下します。重複／隣接する「クラスター」には必須です。segment でヘッダー／フッターの提案を解決できます | | insert_image | URL またはローカルファイルからインライン画像を挿入します。位置、サイズ、左／中央／右揃えを指定できます。segment: "header"（および createSegment）を指定すると、繰り返し表示されるレターヘッドにロゴを配置できます | | download_images | 文書に埋め込まれた画像をローカルフォルダーにダウンロードします（read_doc の画像マーカーと組み合わせて使用します。公開時の操作とは逆になります） | | insert_table | 行×列のテーブルを挿入します。データを入力でき（セルではインライン Markdown を使用可能）、列ごとの align、列幅、ヘッダーの網かけを指定できます。レターヘッドのテーブルには segment／createSegment を指定します | | edit_table | テーブル構造を操作します。行または列を挿入／削除します（セルのテキストでテーブルを特定する、対象を絞った操作です）。ヘッダー／フッターのテーブルには segment を指定します | | set_table_style | 既存のテーブルのスタイルを設定します（セルのテキストで特定します）。セルのパディング、背景、セルの枠線（width: 0 で枠線なし）、列幅、固定するヘッダー行を設定できます。テーブル／行／列／セルを対象範囲として指定できます。ヘッダー／フッターのテーブルには segment を指定します | | get_table_style | テーブルのスタイルを読み取ります（セルのテキストで特定します）。列幅、固定されたヘッダー行、および一致したセルのパディング、背景、辺ごとの枠線を取得できます。set_table_style に対応する読み取りツールです | | list_comments / add_comment / resolve_comment | コメントスレッドを操作します（add_comment は replyTo を指定して返信することもできます） | | drive | Drive をファイルシステムとして操作します：ls find mkdir cp mv。パスには / または ~（マイドライブ）、/shared/<drive>、/shared-with-me、/lost+found を指定します。それ以外はすべて ID として扱われます。cp は Markdown では往復変換できないもの（ヘッダー／フッター、画像サイズ、正確な書式）を保持するため、テンプレートを作り直すよりも cp の使用を推奨します。Drive をファイルシステムとして操作するを参照してください。文書はタブのフォルダーです。ls <doc> はタブを一覧表示し、ls <folder> は各文書のタブ数を表示します。パスをタブまで続けて指定できます（/Work/Contract/Part 2/Ch.4）。mv では名前変更、入れ子化（dst は別のタブ）、入れ子の解除（dst は文書）、および index を指定したタブの並べ替えができます（index: 0 を指定した mv <doc>/Summary <doc>/Summary は、その場で順序を変更します）。タブを別の文書に移動することはできず、タブの cp は拒否されます | | list_permissions / share_doc / unshare_doc | 共有を操作します（share_doc は特定のユーザーとの共有とリンクを知っている全員との共有の両方に対応します）。list_permissions は、作成時に Workspace が追加するドメイン全体への権限付与を含め、すべての対象ユーザーを表示します。unshare_doc は permissionId でそれらの権限を取り消します。取り消しはどのバージョン履歴にも表示されないため、expectRole が必要です | | list_accounts | 認証済みの Google アカウントを一覧表示します | | set_project_default / get_project_config | このプロジェクトのデフォルトのアカウントとフォルダーを設定／表示します（.gdocs-mcp.json に書き込みます） | すべてのドキュメントツールでは、ドキュメントを指定するpath（ID、URL、/Work/Contract、/Work/Contract/Ch.4など）を1つ受け取り、任意でaccount（デフォルトの上書き）も指定できます。タブが1つのドキュメントでは、タブを指定する手順は不要です。複数のタブがある場合、タブを指定するまでは拒否され、すべてのタブのパスが表示されます。同じ名前のタブが2つある場合（またはフォルダーとドキュメントが同じ名前の場合）も拒否され、それぞれの候補のIDが表示されます。

ファイルシステムとしてのDrive

Driveのナビゲーションには、シェルを使う1つのツールを使用します。モデルはすでにシェルを知っているためです。引数は位置によって指定し、各コマンドで異なります。ターミナルでの指定方法とまったく同じです。

{ "cmd": "ls",    "args": ["/Work/2026"] }
{ "cmd": "find",  "args": ["quarterly report", "-type", "d"] }
{ "cmd": "mkdir", "args": ["-p", "/Work/2027/Q1"] }
{ "cmd": "cp",    "args": ["/Work/Template", "/Work/2027/Q1/Report"] }
{ "cmd": "mv",    "args": ["/Work/Roof", "/Archive"], "expectName": "Roof" }

path	は
/… または ~/…	マイドライブ
/shared/<drive name>/…	共有ドライブ
/shared-with-me	他のユーザーが共有したファイルのうち、自分ではどこにも保存していないもの
/lost+found	どのフォルダーにも入っていない、自分が所有するファイル — 詳細は下記
上記以外	DriveのIDまたはURL。他のツールから取得したIDもそのまま貼り付けられます

フラグとオペランドは任意の順序で指定できます（cp -r a b、cp a b -r、cp a -r b）。--を指定すると、それ以降はオプションとして解釈されません。

Driveがファイルシステムとは異なる3つの点。 用語は、実態に合う場合に限って借用しています。実態に合わない場合は拒否します。

• 1つのフォルダー内で同じ名前のファイルを複数作成でき、照合時には大文字と小文字が区別されません。モデルが学習したファイルシステムには、どちらの性質もありません。そのため、モデルは確認が必要だとは考えないでしょう。複数の項目に一致するパスは、候補を表示して必ず拒否され、推測で選ばれることはありません。また、cp／mvもそのような状態を作成することを拒否し、名前解決で曖昧さが生じる状態を作りません。
• cp -rはありません。 Driveのfiles.copyはフォルダーを拒否します（DriveのウェブUIからもフォルダーはコピーできません）。そのため、フォルダーに対してcpを実行すると、処理が中途半端に進むのではなく、その旨が説明されます。
• mvで/shared/…に移動すると、ファイルの所有権が移ります。 ファイルシステム間でシェルのmvを実行してもファイルの所有権は移りませんが、共有ドライブに移動すると、ファイルの所有権がその組織に移り、ユーザー側から元に戻せなくなります。この操作にはacceptOwnershipTransfer: trueが必要です。

パスで見つかる範囲は、findより狭くなります。 親フォルダーのないファイルも開いたり検索で見つけたりできますが、パスで指定することはできません。ツリーをたどる方法では、決して表示されません。完全な情報を得るにはfindを使います。こうしたファイルは/lost+foundに表示されます。

rmはありません。#47をご覧ください。

既知の制限事項

これらはバグではなく、Google API の制約です。主な制約を以下に示します。API 上の理由とそれぞれの回避策を含む完全なリファレンスは、docs/limitations.md をご覧ください。

• 提案を作成することはできません。 提案モードでは API による書き込みができないため、すべての編集が直接（テキストに即時反映）行われます。apply_suggestions は既存の提案のみを解決します。書き込みを行うツールは、その旨を明示します。
• 提案の作成者／タイムスタンプは取得できません。提案はドキュメント内の順序で一覧表示されます。
• API 経由で作成されたコメントはテキストに固定されず、Drive が返すのは作成者の 名前 のみです（メールアドレスは含まれません）。
• 画像はインラインのみです（フローティング配置や x,y 座標による配置はできません）。また、Google は埋め込み画像をダウンスケールして再エンコードするため、取得したコピーはバイト単位で元の画像と一致しません。
• ヘッダーとフッターは別々のコンテンツツリーであり、本文には含まれません。各コンテンツツール（read_doc、edit_doc、insert_content、insert_image、insert_table、edit_table、set_table_style、list_suggestions、apply_suggestions）では、それらにアクセスするための segment: "header" | "footer" と、ドキュメントに複数のヘッダーまたはフッターがある場合の page を指定します。
• スタイルは Markdown 内の CSS で指定します。read_doc は名前付きスタイルの <style> ブロックを冒頭に表示し、段落やテキストのまとまりがそのスタイルのルールと異なる場合は style="…" を表示します。edit_doc でスタイルを変更でき（同じ語句に新しいマークアップを適用する編集はスタイルのみの編集です）、書き込みツールでも同じ CSS を使用できます。使用できるプロパティは限られており（text-align、line-height、margin-*、text-indent、font-*、text-decoration、color。単位は pt）、それ以外はリクエスト送信前に拒否されます。テーブルの詳細なスタイル設定には set_table_style を使用します。コードブロックはまだ Markdown からレンダリングされません（ロードマップ）。

各制限への対処方法やその提示方法を含む全項目については、docs/limitations.md の表をご覧ください。

ロードマップ

• Markdown ライターでのコードブロック対応 — 残る Tier-2 ブロックタイプです（テーブルと画像はすでにレンダリングでき、insert_table／insert_image の単独ツールもあります）。

提案の作成者／タイムスタンプはロードマップの対象ではありません。一般的な提案には API 上の手段がありません（docs/limitations.md をご覧ください）。

「原稿の同期」というユースケース（章ファイル ⇄ タブ、提案の確認、マージ）は、意図的にサーバー機能として実装していません。AI エージェントがこれらのプリミティブを通じて処理を調整します。DESIGN.md §10b をご覧ください。

開発

npm install
npm run build      # tsc
npm test           # vitest
npm run typecheck

アーキテクチャ全体と、その背景にある実証的な知見については、DESIGN.md をご覧ください。

謝辞

アーキテクチャとアプローチの策定にあたり、先行するオープンソースの Google Docs MCP サーバー、特に @a-bonus/google-docs-mcp と taylorwilsdon/google_workspace_mcp を参考にしました。

ライセンス

MIT © Dasasian