google-docs

Google Docs Workspace MCP サーバー

AI アシスタント向けに Google Docs 連携を提供する MCP（Model Context Protocol）サーバーです。個人の Google アカウント（OAuth2 経由）と Google Workspace アカウント（ドメイン全体の委任を設定したサービスアカウント経由）の両方に対応しています。

機能

• ドキュメントの読み取り：ドキュメント ID または共有可能な URL を指定して、Google ドキュメントの本文全体、または見出しのアウトラインのみを取得します
• ドキュメントの作成：初期コンテンツを指定して、新しい Google ドキュメントを作成します
• ドキュメントの編集：
  • ドキュメントの末尾にテキストを追加します
  • 指定したインデックスにテキストを挿入します
  • 文字列のすべての出現箇所を置換します
  • 生の documents.batchUpdate リクエストを適用して、構造を完全に制御します
• ドキュメントの削除：デフォルトでは Drive のゴミ箱に移動します。明示的なフラグを指定すると完全に削除できます
• ドキュメントのエクスポート：Markdown、HTML、プレーンテキスト、PDF、DOCX、ODT、RTF、EPUB にエクスポートします
• ドキュメントの共有（制限あり）：ユーザー、グループ、ドメイン、またはリンクを知っている全員に、閲覧、コメント、編集の権限を付与します
• 2 つの認証方法：個人アカウント向けの OAuth2、Google Workspace 向けのサービスアカウント
• 権限の制限：GOOGLE_DOCS_ENABLED_TOOLGROUPS によって、ツールをグループ単位で制限します

インストール

npm install google-docs-workspace-mcp-server

または、npx で直接実行します。

npx google-docs-workspace-mcp-server

認証

このサーバーは 2 つの認証モードに対応しています。アカウントの種類に合った方法を選択してください。

オプション 1：OAuth2（個人の Google アカウント）

個人の @gmail.com アカウント、または Workspace 管理者のアクセス権を持たない Google アカウントで使用します。

前提条件

1. Google Cloud Console にアクセスします
2. プロジェクトを作成するか、既存のプロジェクトを選択します
3. Google Docs API と Google Drive API を有効にします
4. OAuth 同意画面を設定します：
   • ユーザーの種類として External を選択します
   • 自分をテストユーザーに追加します
   • 7 日ごとに更新トークンが期限切れにならないよう、アプリを公開します（同意画面で「Publish」をクリック）。個人利用の場合、Google による完全な検証は不要です
5. OAuth 2.0 認証情報を作成します：
   • アプリケーションの種類として Desktop app を選択します
   • 重要：アプリを公開した_後に_新しい認証情報を作成します
6. クライアント ID とクライアントシークレットをコピーします

更新トークンの取得

組み込みのセットアップコマンドを実行します。

npx google-docs-workspace-mcp-server oauth-setup <client_id> <client_secret>

環境変数で認証情報を渡すこともできます。

GOOGLE_DOCS_OAUTH_CLIENT_ID=... GOOGLE_DOCS_OAUTH_CLIENT_SECRET=... npx google-docs-workspace-mcp-server oauth-setup

ポートが競合していますか？ ポート 3000 がすでに使用中の場合は、別のポートを指定します。

PORT=3001 npx google-docs-workspace-mcp-server oauth-setup <client_id> <client_secret>

デスクトップアプリの認証情報では、任意のポートで http://localhost へのリダイレクトが自動的に許可されるため、Google Cloud Console で追加の設定を行う必要はありません。

これにより、ブラウザーが開いて Google にサインインし、更新トークンが表示されます。この操作は一度だけ行えば十分です。OAuth 同意画面が公開されている限り、更新トークンの有効期限は切れません。

環境変数（OAuth2）

変数	必須	説明
GOOGLE_DOCS_OAUTH_CLIENT_ID	はい	Google Cloud Console の OAuth2 クライアント ID
GOOGLE_DOCS_OAUTH_CLIENT_SECRET	はい	OAuth2 クライアントシークレット
GOOGLE_DOCS_OAUTH_REFRESH_TOKEN	はい	セットアップスクリプトで取得した更新トークン
GOOGLE_DOCS_ENABLED_TOOLGROUPS	いいえ	ツールグループのカンマ区切りリスト（デフォルト：すべて）

Claude Desktop の設定（OAuth2）

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["google-docs-workspace-mcp-server"],
      "env": {
        "GOOGLE_DOCS_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_DOCS_OAUTH_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_DOCS_OAUTH_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

オプション 2：サービスアカウント（Google Workspace）

ドメイン管理者がドメイン全体の委任を許可できる Google Workspace 組織で使用します。

前提条件

1. Google Cloud Console にアクセスします
2. プロジェクトを作成するか、選択します
3. Google Docs API と Google Drive API を有効にします
4. ドメイン全体の委任を有効にしたサービスアカウントを作成します
5. Google Workspace Admin Console で、サービスアカウントに次のスコープへのアクセス権を付与します：
   • https://www.googleapis.com/auth/documents（ドキュメントの読み取りと編集）
   • https://www.googleapis.com/auth/drive（偽装するユーザーの Drive への完全な読み取り／書き込みアクセス。エクスポート、コメントの読み取り、このアプリが作成していないファイルを含む任意の既存ドキュメントの管理に必要です）
6. JSON キーファイルをダウンロードします

環境変数（サービスアカウント）

変数	必須	説明
GOOGLE_DOCS_SERVICE_ACCOUNT_CLIENT_EMAIL	はい	サービスアカウントのメールアドレス
GOOGLE_DOCS_SERVICE_ACCOUNT_PRIVATE_KEY	はい	サービスアカウントの秘密鍵（PEM 形式）
GOOGLE_DOCS_IMPERSONATE_EMAIL	はい	偽装するメールアドレス
GOOGLE_DOCS_ENABLED_TOOLGROUPS	いいえ	有効にするツールグループのカンマ区切りリスト（デフォルト：すべてのグループ）

サービスアカウントの JSON キーファイルで client_email と private_key の値を確認できます。

Claude Desktop の設定（サービスアカウント）

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["google-docs-workspace-mcp-server"],
      "env": {
        "GOOGLE_DOCS_SERVICE_ACCOUNT_CLIENT_EMAIL": "[email protected]",
        "GOOGLE_DOCS_SERVICE_ACCOUNT_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----",
        "GOOGLE_DOCS_IMPERSONATE_EMAIL": "[email protected]"
      }
    }
  }
}

注記： 秘密鍵は、次のいずれかの方法で指定できます：

1. 上記の例のように、改行を \n で表してキーを直接使用する
2. 改行を保持するシェルから環境変数を設定する

ツールグループ

サーバーは、権限ベースのアクセス制御のために3つのツールグループをサポートしています：

グループ	含まれるツール	リスクレベル
readonly	get_document、get_document_outline、export_document、list_comments	低
readwrite	読み取り専用ツールすべて + create_document、update_document、delete_document、append_text、insert_text、replace_text	中
readwrite_external	読み取り／書き込みツールすべて + share_document	高

デフォルトでは、すべてのツールグループが有効です。アクセスを制限するには、GOOGLE_DOCS_ENABLED_TOOLGROUPS 環境変数を設定します：

# Read-only access (no writes or sharing)
GOOGLE_DOCS_ENABLED_TOOLGROUPS=readonly

# Read and write, but no sharing
GOOGLE_DOCS_ENABLED_TOOLGROUPS=readwrite

# Full access including sharing (default)
GOOGLE_DOCS_ENABLED_TOOLGROUPS=readwrite_external

セキュリティに関する注記： share_document ツールは、組織外のユーザーにもアクセス権を付与できるため、純粋に内部向けの編集よりリスクが高く、別の readwrite_external グループに含まれています。

利用可能なツール

document_id を受け取るすべてのツールでは、Google Docs ID（例：1AbCdEf...）または共有可能な Docs URL（例：https://docs.google.com/document/d/1AbCdEf.../edit）を指定できます。サーバーが ID を自動的に抽出します。

get_document

Google ドキュメントを取得し、タイトル、アウトライン、本文全体を返します。

パラメーター：

• document_id（文字列、必須）：Google Docs ID または URL
• format（文字列、任意）：人が読みやすい出力には text（デフォルト）、または未加工の documents.get API リソースには json

get_document_outline

ドキュメントの見出し構成のみを返します。長いドキュメントの全本文を取得せずに概要を把握するのに便利です。

パラメーター：

• document_id（文字列、必須）：Google Docs ID または URL

create_document

新しい Google ドキュメントを作成します。

パラメーター：

• title（string、必須）：ドキュメントのタイトル
• initial_content（string、任意）：新しいドキュメントに挿入するプレーンテキスト

update_document

未加工の documents.batchUpdate リクエストを適用します。より用途を絞ったツールでは対応していない Docs API 操作（段落スタイルの適用、表の挿入、名前付き範囲の操作など）を行うための手段です。

パラメーター：

• document_id（string、必須）：Google Docs の ID または URL
• requests（array、必須）：documents.batchUpdate リクエストオブジェクトの配列（API リファレンス）

例：

{
  "document_id": "1AbCdEf...",
  "requests": [
    {
      "insertText": {
        "location": { "index": 1 },
        "text": "Hello, world!\n"
      }
    },
    {
      "updateParagraphStyle": {
        "range": { "startIndex": 1, "endIndex": 14 },
        "paragraphStyle": { "namedStyleType": "HEADING_1" },
        "fields": "namedStyleType"
      }
    }
  ]
}

append_text

ドキュメントの末尾にテキストを追加します。本文の末尾のインデックスは自動的に解決されます。

パラメーター：

• document_id（string、必須）：Google Docs の ID または URL
• text（string、必須）：追加するテキスト

insert_text

指定したインデックスにテキストを挿入します。

パラメーター：

• document_id（string、必須）：Google Docs の ID または URL
• index（number、必須）：挿入位置のインデックス（1 以上である必要があります）
• text（string、必須）：挿入するテキスト

replace_text

ドキュメント全体からテキストを検索して置換します。置換された箇所の数を報告します。

パラメーター：

• document_id（string、必須）：Google Docs の ID または URL
• find（string、必須）：検索する文字列
• replace（string、必須）：置換後の文字列
• match_case（boolean、任意）：大文字と小文字を区別して検索するかどうか（デフォルト：false）

delete_document

デフォルトではドキュメントを Drive のゴミ箱に移動します。完全に削除することもできます。

パラメーター：

• document_id（string、必須）：Google Docs の ID または URL
• permanent（boolean、任意）：true の場合、ゴミ箱に移動せず完全に削除します（デフォルト：false）

export_document

ドキュメントを別の形式でエクスポートします。

パラメーター：

• document_id（string、必須）：Google Docs の ID または URL
• format（string、必須）：markdown、html、txt、pdf、docx、odt、rtf、epub のいずれか

テキスト形式（markdown、html、txt）はインラインで返されます。バイナリ形式（pdf、docx、odt、rtf、epub）は base64 エンコードされて返されます。

list_comments

スレッド形式の返信や解決状態を含め、ドキュメントのコメントを一覧表示します。Drive の comments.list API を読み取り、各コメントの作成者、タイムスタンプ、解決済み／未解決の状態、コメントの対象となる引用テキスト、コメント本文、返信（スレッドを解決または再開した返信を含む）を表示します。

パラメーター：

• document_id（string、必須）：Google Docs の ID または URL
• include_resolved（boolean、任意）：解決済み（クローズ済み）のスレッドを含めます（デフォルト：true）。未解決のコメントのみを表示するには false を指定します。
• include_deleted（boolean、任意）：削除済みのコメントを含めます（デフォルト：false）

このアプリが作成していないドキュメントのコメントを読み取るには、https://www.googleapis.com/auth/drive スコープが必要です。より限定的な drive.file スコープだけでは不十分です。

share_document

ユーザー、グループ、ドメイン、またはリンクを知っている全員にアクセス権を付与します。readwrite_external グループへの所属が必要です。

パラメーター：

• document_id（string、必須）：Google Docs の ID または URL
• type（string、必須）：user、group、domain、anyone のいずれか
• role（string、必須）：reader、commenter、writer のいずれか
• email_address（string、条件付き）：type=user または type=group の場合に必須
• domain（string、条件付き）：type=domain の場合に必須
• send_notification_email（boolean、任意）：Google からメール通知を送信するかどうか（デフォルト：true）

開発

セットアップ

# Install dependencies
npm run install-all

# Build
npm run build

# Run in development mode
npm run dev

テスト

このサーバーでは、4段階のテスト戦略を採用しています。

段階	コマンド	実際の API にアクセスしますか？	必要な認証情報
機能テスト	npm test	いいえ	なし
統合テスト	npm run test:integration	いいえ	なし
E2E	npm run test:e2e	はい	OAuth2 またはサービスアカウント（暗号化済み）
手動テスト	npm run test:manual	はい	OAuth2 またはサービスアカウント（自身の .env）

機能テストと統合テストは、コミットのたびに CI で実行されます。E2E テストは、固定されたテストドキュメントと、リポジトリに（暗号化された状態で）コミットされたリフレッシュトークンを使用して、実際の Google Docs API と Drive API に対して実行されます。

E2E テストの実行

E2E テストは tests/e2e/ にあり、実際の Google API に対して MCP サーバー全体をテストします。以下が含まれます。

• 固定された既存のテストドキュメントに対する読み取り専用の検証
• 新しいドキュメントの作成 → 変更 → エクスポート → 共有 → 削除をエンドツーエンドで行う、自動クリーンアップ付きのライフサイクルテスト
• 存在しないドキュメント ID に対するエラー処理の確認

テストスイート全体は、認証モードごとに 1 回ずつ 実行されます。テストスイートが設定されている場合は、OAuth2（個人アカウント）とサービスアカウント（Workspace の代理認証）の両方が必ずテストされます。これにより、認証モード固有のバグ（トークンの更新と JWT 署名の違い、代理認証、サービスアカウント固有の subject クレーム）が本番環境に到達する前に検出されます。認証情報が一部だけ設定されている場合、テストスイートは即座に失敗します。OAuth またはサービスアカウントの環境変数が 1 つでも設定されている場合は、必要な環境変数をすべて設定する必要があります。そうでない場合、モジュールの読み込み時にエラーが発生します。「認証情報なし」が有効なのは、MCP_SERVERS_MASTER_KEY を利用できないフォークの PR の場合のみです。その場合、テストスイート全体がスキップされます。

認証情報は tests/e2e/.env.enc に暗号化して保存され、mcp-servers/ ワークスペース全体で共有されている MCP_SERVERS_MASTER_KEY を使用して実行時に復号されます。

ローカルで E2E テストを実行するには：

# 1. Decrypt the e2e credentials (one-time per checkout)
cd mcp-servers
MCP_SERVERS_MASTER_KEY="<key>" ./scripts/decrypt-credentials.sh google-docs

# 2. Run the suite (this also rebuilds the server and the test client)
cd servers/google-docs
npm run test:e2e

マスターキーは 1Password の「MCP Servers Master Key」にあります。アクセス権のあるチームメイトに問い合わせてください。復号された .env は gitignore の対象で、コミットされるのは .env.enc のみです。

tests/e2e/.env がない場合や、認証情報が無効な場合、テストスイートは失敗せずに正常にスキップされます。そのため、マスターキーを利用できないフォーク上の CI が失敗することはありません。

固定されたテストドキュメント、OAuth スコープ、トークンのローテーション、サービスアカウントのプロビジョニング手順、およびテスト対象のツール一覧については、tests/e2e/STATE.md を参照してください。

E2E 認証情報の更新

リフレッシュトークンが取り消された場合、有効期限が切れた場合、または OAuth クライアントに変更があった場合は、新しいリフレッシュトークンを発行して再暗号化してください。

# 1. Mint a new refresh token via the OAuth flow (see tests/e2e/STATE.md for the full procedure)
# 2. Update tests/e2e/.env with the new GOOGLE_DOCS_OAUTH_REFRESH_TOKEN
# 3. Re-encrypt
cd mcp-servers
MCP_SERVERS_MASTER_KEY="<key>" ./scripts/encrypt-credentials.sh google-docs
# 4. Commit the updated .env.enc
git add servers/google-docs/tests/e2e/.env.enc

ライセンス

MIT