Ultimate Google Docs & Drive MCP Server

Google ドキュメント、スプレッドシート、ドライブ、Gmail、カレンダー MCP サーバー

Claude Desktop、Cursor、または任意の MCP クライアントを Google ドキュメント、Google スプレッドシート、Google ドライブ、Gmail、Google カレンダーに接続します。

---

クイックスタート

1. Google Cloud OAuth クライアントを作成する

1. Google Cloud Console にアクセスします
2. プロジェクトを作成するか、選択します
3. Google Docs API、Google Sheets API、Google Drive API、Gmail API、Google Calendar API を有効にします
4. OAuth 同意画面を設定します（External を選択し、メールアドレスをテストユーザーとして追加し、Docs／Sheets／Drive のスコープとともに gmail.modify および calendar.events スコープを追加します）
5. OAuth クライアント ID を作成します（デスクトップアプリの種類）
6. 確認画面から Client ID と Client Secret をコピーします

詳細が必要ですか？ このページの下部にある手順ごとの説明をご覧ください。

2. 認証する

GOOGLE_CLIENT_ID="your-client-id" \
GOOGLE_CLIENT_SECRET="your-client-secret" \
npx -y @a-bonus/google-docs-mcp auth

Google 認証を行うため、ブラウザーが開きます。承認すると、更新トークンが ~/.config/google-docs-mcp/token.json に保存されます。

3. MCP クライアントに追加する

Claude Desktop／Cursor／Windsurf：

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@a-bonus/google-docs-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

MCP クライアントが必要とするときに、サーバーが自動的に起動します。

リモートデプロイ（Cloud Run）

チーム向けに一度デプロイすれば、ローカルへのインストールは不要です。サーバーは MCP OAuth 2.1 を使用するため、MCP クライアントが認証を自動的に処理します。

gcloud run deploy google-docs-mcp \
  --source . \
  --region europe-west3 \
  --port 8080 \
  --allow-unauthenticated \
  --set-env-vars "^|^MCP_TRANSPORT=httpStream|BASE_URL=https://your-service.run.app|GOOGLE_CLIENT_ID=...|GOOGLE_CLIENT_SECRET=...|TOKEN_STORE=firestore|JWT_SIGNING_KEY=your-secret-key"

その後、各ユーザーは URL を MCP クライアントに追加するだけです。npx も、トークンも、ローカルのセットアップも不要です。

{
  "mcpServers": {
    "google-docs": {
      "type": "streamableHttp",
      "url": "https://your-service.run.app/mcp"
    }
  }
}

初回接続時に、MCP クライアントから Google へのサインインを求められます。詳しくはリモートデプロイをご覧ください。

---

何ができますか？

Google ドキュメント、スプレッドシート、ドライブで利用できるツール：

Google Docs

ツール	説明
readDocument	コンテンツをプレーンテキスト、JSON、または Markdown として読み取ります
appendText	ドキュメントにテキストを追加します
insertText	指定した位置にテキストを挿入します
deleteRange	インデックス範囲を指定してコンテンツを削除します
modifyText	ドキュメント内のテキストを置換、先頭に追加、または変換します
findAndReplace	ドキュメント全体からテキストを検索して置換します
findElement	テキストの出現箇所（インデックス範囲付き）を特定するか、段落／表を一覧表示します
listTabs	複数タブのドキュメント内にあるすべてのタブを一覧表示します
addTab	ドキュメントに新しいタブを追加します
renameTab	ドキュメントのタブ名を変更します
replaceDocumentWithMarkdown	ドキュメント全体のコンテンツを Markdown で置き換えます
replaceRangeWithMarkdown	指定した範囲を Markdown コンテンツで置き換えます
appendMarkdown	Markdown 形式のコンテンツを追加します
applyTextStyle	太字、斜体、色、フォントサイズ、リンクを設定します
applyParagraphStyle	配置、間隔、インデントを設定します
insertTable	空の表を作成します
insertTableWithData	データをあらかじめ入力した表を作成します
insertPageBreak	改ページを挿入します
insertSectionBreak	セクション区切り（NEXT_PAGE または CONTINUOUS）を挿入します
updateSectionStyle	セクションのスタイルを更新します：向き、余白を変更します
insertImage	URL またはローカルファイルから画像を挿入します

コメント

ツール	説明
listComments	作成者と日付を含むすべてのコメントを表示します
getComment	返信を含む特定のコメントを取得します
addComment	テキストに紐付けてコメントを作成します
replyToComment	既存のコメントに返信します
resolveComment	コメントを解決済みとしてマークします
deleteComment	コメントを削除します

提案

書き込みツールでは suggestMode: true を指定すると、編集を直接反映するのではなく、レビュー用の保留中の提案として適用できます（Node 22+ および googleapis@184 が必要です）。

ツール	説明
listSuggestions	作成者、日付、ID を含む保留中の提案を表示します
manageSuggestions	保留中の提案スレッドを承認、却下、または削除します

Google Sheets

ツール	説明
readSpreadsheet	範囲（A1表記）のデータを読み取ります
writeSpreadsheet	範囲にデータを書き込みます
batchWrite	1回の呼び出しで複数の範囲に書き込みます
appendRows	シートに行を追加します
clearRange	セルの値をクリアします
createSpreadsheet	新しいスプレッドシートを作成します
addSheet	シート／タブを追加します
deleteSheet	シート／タブを削除します
duplicateSheet	同じスプレッドシート内でシートを複製します
copySheetTo	シートを別のスプレッドシートにコピーします
renameSheet	シート／タブの名前を変更します
getSpreadsheetInfo	メタデータとシート一覧を取得します
listSpreadsheets	スプレッドシートを検索します
formatCells	範囲の太字、色、配置、垂直方向の配置、折り返し方法を設定します
copyFormatting	ある範囲の書式を別の範囲にコピーします
readCellFormat	セル範囲の書式の詳細を読み取ります
setCellBorders	上／下／左／右／内側の罫線をスタイルと色を指定して設定します
freezeRowsAndColumns	ヘッダー行／列を固定します
setDropdownValidation	セルのドロップダウンリストを追加／削除します
setColumnWidths	列幅をピクセル単位で設定します
setRowHeights	行の高さをピクセル単位で設定します
autoResizeColumns	内容に合わせて列幅を自動調整します
autoResizeRows	内容に合わせて行の高さを自動調整します
protectRange	範囲またはシート全体をロックします（警告のみ、または完全にロック）
addConditionalFormatting	条件付き書式ルールを追加します
getConditionalFormatting	インデックス付きで条件付き書式ルールを一覧表示します（JSON）
deleteConditionalFormatting	インデックスを指定して条件付き書式ルールを削除します
groupRows	折りたたみ可能なセクション用に行をグループ化します
ungroupAllRows	すべての行グループを解除します
createSheetsComment	必要に応じてセルへの直接リンクを付けてスプレッドシートのコメントを作成します
createSheetsCellNote	セルまたは範囲に付属するネイティブのセルメモを作成します
insertChart	データからグラフを作成します
deleteChart	グラフを削除します

Google Sheets のテーブル

ツール	説明
createTable	列の型を指定して、新しい名前付きテーブルを作成します
listTables	スプレッドシートまたはシート内のすべてのテーブルを一覧表示します
getTable	名前または ID を指定して、テーブルの詳細なメタデータを取得します
deleteTable	テーブルを削除します（データの消去は任意）
updateTableRange	テーブルのサイズを変更します（行や列の追加・削除）
appendTableRows	テーブルに行を追加します（テーブルに対応した挿入）

Google Drive

ツール	説明
listDocuments	ドキュメントを一覧表示します。日付による絞り込みも可能です
searchDocuments	名前または内容で検索します
getDocumentInfo	ドキュメントのメタデータを取得します
createDocument	新しいドキュメントを作成します
createDocumentFromTemplate	既存のテンプレートから作成します
createFolder	フォルダーを作成します
listFolderContents	フォルダーの内容を一覧表示します
getFolderInfo	フォルダーのメタデータを取得します
moveFile	ファイルを別のフォルダーに移動します
copyFile	ファイルを複製します
renameFile	ファイル名を変更します
deleteFile	ゴミ箱に移動するか、完全に削除します
listDriveFiles	フィルターを指定して、Drive 内のあらゆる種類のファイルを一覧表示します
searchDriveFiles	Drive 内のすべてのファイルを名前または内容で検索します
downloadFile	ファイルの内容をダウンロードします
createMarkdownFile	ネイティブの Markdown（.md）ファイルを作成します
readMarkdownFile	ネイティブの .md ファイルの生のソースを読み取ります
updateMarkdownFile	.md ファイルの生のソースを置き換えるか、追記します

Gmail

ツール	説明
listMessages	Gmail の検索構文（is:unread、from:、newer_than: など）を使ってメッセージを一覧表示または検索します
getMessage	デコード済みのヘッダー、プレーンテキスト本文、HTML 本文、添付ファイルのメタデータを含む単一のメッセージを取得します
sendEmail	プレーンテキストのメールを送信します。replyToMessageId を使った cc／bcc とスレッド形式の返信に対応しています
trashMessage	メッセージをゴミ箱に移動します（元に戻せます。Gmail の UI で削除をクリックするのと同じです）
modifyMessageLabels	メッセージのラベルを追加または削除します。スター付け、アーカイブ（INBOX を削除）、既読にする（UNREAD を削除）際に使います
listLabels	すべてのシステムラベルとカスタムラベルを ID とともに一覧表示します
createDraft	すぐに送信する代わりに下書きを作成します。作成／確認／送信のワークフローに使います
listDrafts	既存の下書きを、宛先、件名、スニペットとともに一覧表示します
getDraft	完全なヘッダーと本文を含む単一の下書きを取得します
updateDraft	既存の下書きの内容を置き換えます（パッチではなく、全体を置き換えます）
sendDraft	ID を指定して既存の下書きを送信します
deleteDraft	下書きを完全に削除します（ゴミ箱には移動せず、消去されます）
triageInbox	複合： 未読メッセージを内容とヒューリスティックによるフラグ（ニュースレター、会議、アクション）とともに取得し、受信トレイを一括でトリアージします

Google Calendar

ツール	説明
listEvents	q、timeMin、timeMax、maxResults を使って予定を一覧表示または検索します（デフォルトではメインのカレンダーを使用します）
createEvent	タイトル、開始／終了時刻、説明、場所、参加者、オプションの Google Meet リンクを指定して予定を作成します
updateEvent	PATCH 形式の更新です。渡したフィールドのみ変更されます。日時の変更、タイトルの変更、参加者の変更に使います
deleteEvent	予定を完全に削除します。任意の sendUpdates を指定すると、参加者にキャンセルのメールを送信します
quickAddEvent	自然言語で予定を作成します："Lunch with Sarah tomorrow 12pm" — 残りは Google が解析します

Apps Script

自動化を自動化します。ユーザーにエディターへ手作業でコードを貼り付けるよう指示する代わりに、Doc や Sheet の背後で動く Apps Script（onEdit トリガー、カスタムメニュー、スケジュール済みジョブなど）を作成、編集します。

ツール	説明
createAppsScriptProject	parentId を指定して、Doc／Sheet／Slides／Form に紐付けられたプロジェクトを作成し、同じ呼び出しで初期ファイルを書き込みます
getAppsScriptContent	プロジェクトのファイルを読み取ります。素早く一覧を取得するには includeSource: false を、保存済みのバージョンを読み取るには versionNumber を指定します
updateAppsScriptContent	ファイルを書き込みます。merge（デフォルト）は同名のファイルを置き換えて、残りは維持します。replace はプロジェクトを指定したファイルだけで構成します

通常のセットアップに加えて、次の2つが必要です。

1. Apps Script API は、https://script.google.com/home/usersettings でGoogle アカウントごとに有効にする必要があります。デフォルトでは無効になっており、メッセージに「Apps Script API」と含まれる 403 エラーが発生した場合は、この手順が未完了です。
2. SCOPES に含まれる script.projects スコープが必要です。既存のインストールでは、これを適用するために一度再認証する必要があります。

---

使用例

Google Docs

"Read document ABC123 as markdown"
"Append 'Meeting notes for today' to document ABC123"
"Make the text 'Important' bold and red in document ABC123"
"Replace the entire document with this markdown: # Title\n\nNew content here"
"Insert a 3x4 table at index 50 in document ABC123"

Google Sheets

"Read range A1:D10 from spreadsheet XYZ789"
"Write [[Name, Score], [Alice, 95], [Bob, 87]] to range A1 in spreadsheet XYZ789"
"Create a new spreadsheet titled 'Q1 Report'"
"Format row 1 as bold with a light blue background in spreadsheet XYZ789"
"Freeze the first row in spreadsheet XYZ789"
"Add a dropdown with options [Open, In Progress, Done] to range C2:C100"
"Create a table named 'Tasks' in range A1:D10 with columns: Task (TEXT), Status (DROPDOWN: 'Not Started','In Progress','Done'), Priority (NUMBER)"
"Add a medium solid border around A1:D10 in spreadsheet XYZ789"
"Protect the header row so collaborators can't accidentally edit it"
"Auto-fit row heights for rows 2–50 after wrapping text"

Google Drive

"List my 10 most recent Google Docs"
"Search for documents containing 'project proposal'"
"Create a folder called 'Meeting Notes' and move document ABC123 into it"

Gmail

"Show me my 20 most recent unread emails"
"Search Gmail for messages from [email protected] in the last 7 days"
"Read the full body of message ID 18c3f4a2b1d9"
"Send an email to [email protected] with the subject 'Weekly update' and this body..."
"Reply to message 18c3f4a2b1d9 with 'Thanks, confirmed.'"
"Star message 18c3f4a2b1d9 and archive it"
"Move message 18c3f4a2b1d9 to Trash"
"List all my Gmail labels"
"Draft a reply to that email but don't send it yet — let me review first"
"Show me my drafts, then send the one to bob@"
"Triage my unread inbox: tell me which 20 emails need attention and which are noise"

Google Calendar

"What's on my calendar this week?"
"Create an event titled 'Project review' tomorrow from 2pm to 3pm Pacific time"
"Quick add: lunch with Alex Friday 12:30"
"Reschedule event abc123 to next Monday at 10am"
"Delete the 'Standup' event tomorrow"
"List all events on my calendar between April 15 and April 22"
"Schedule a 30-minute meeting with [email protected] next Wednesday at 11am with a Google Meet link"

Markdown ワークフロー

サーバーは、Markdown を使った完全な往復ワークフローに対応しています。

1. ドキュメントを Markdown として読み取ります。format='markdown' を指定して readDocument を実行します
2. Markdown をローカルで編集します
3. 変更を反映します。replaceDocumentWithMarkdown を実行します

対応項目：見出し、太字、斜体、取り消し線、リンク、箇条書き／番号付きリスト、水平線。

Docs のライブ検証

リポジトリには、実際の Google Docs API に対して cloneTable を実行する、オプトイン形式のライブ統合テストが含まれています。デフォルトではスキップされます。

必要なもの：

• 有効な GOOGLE_CLIENT_ID と GOOGLE_CLIENT_SECRET
• npx -y @a-bonus/google-docs-mcp auth で認証済みトークンがすでに保存されていること

次のコマンドで実行します。

GOOGLE_DOCS_LIVE_TESTS=1 npm run test:live:docs

このテストでは、一時的なソースおよびターゲットの Google Docs を作成して cloneTable を検証した後、テストファイルを削除します。

---

リモートデプロイ

サーバーを Google Cloud Run（または任意のコンテナホスト）に一元的にデプロイすると、チームはローカルにインストールしなくても利用できます。サーバーは FastMCP に組み込まれた GoogleProvider によるMCP OAuth 2.1を使用します。MCP クライアントが認証フローを自動的に処理します。

サーバーのルート URL（/）にアクセスすると、セットアップ手順と、すぐにコピーできるクライアント設定を確認できます。

環境変数

変数	説明
MCP_TRANSPORT	リモートモードを有効にするには httpStream に設定します（デフォルト：stdio）
BASE_URL	デプロイされたサーバーの公開 URL（OAuth リダイレクトに必須）
GOOGLE_CLIENT_ID	OAuth クライアント ID（Web アプリケーションタイプ）
GOOGLE_CLIENT_SECRET	OAuth クライアントシークレット
MCP_TOOL_GROUPS	登録するツールグループをカンマ区切りで指定します（任意）：docs、drive、sheets、utils、gmail、calendar、script、または all
ALLOWED_DOMAINS	許可する Google Workspace ドメインのカンマ区切りリスト（任意）
PORT	HTTP ポート（デフォルト：8080）
TOKEN_STORE	トークンを永続的に保存するには firestore に設定します（デフォルト：メモリ内）
JWT_SIGNING_KEY	トークンを再起動後も保持するための固定署名キー（未設定の場合は自動生成）
REFRESH_TOKEN_TTL	リフレッシュトークンの有効期間（秒、デフォルト：2592000 / 30 日）
GCLOUD_PROJECT	Firestore 用の GCP プロジェクト ID（TOKEN_STORE=firestore の場合に必須）
MCP_STATELESS	サーバーレスデプロイ（Cloud Run など）では true に設定します — セッション追跡を無効にし、ゼロスケール後も動作するようにします
GOOGLE_DOCS_MCP_DOWNLOAD_ROOTS	stdio モードで downloadFile が書き込み可能なディレクトリ。: 区切り（Windows では ;）。デフォルトは作業ディレクトリです
GMAIL_ATTACHMENT_ROOTS	stdio モードで Gmail の下書きにファイルを添付できるディレクトリ。: 区切り（Windows では ;）。未設定の場合、添付は無効になります

セットアップ

1. GCP プロジェクトを作成し、Docs、Sheets、Drive の各 API を有効にします
2. OAuth クライアントを作成します（Desktop ではなく、Web アプリケーションタイプ）
3. 認証済みリダイレクト URI に {BASE_URL}/oauth/callback を設定します
4. Cloud Run にデプロイします：

gcloud run deploy google-docs-mcp \
  --source . \
  --region europe-west3 \
  --port 8080 \
  --allow-unauthenticated \
  --set-env-vars "^|^MCP_TRANSPORT=httpStream|BASE_URL=https://your-service.run.app|ALLOWED_DOMAINS=yourdomain.com|GOOGLE_CLIENT_ID=...|GOOGLE_CLIENT_SECRET=...|TOKEN_STORE=firestore|JWT_SIGNING_KEY=your-secret-key"

注： ^|^ プレフィックスは、ALLOWED_DOMAINS にカンマが含まれるため、環境変数の区切り文字を , から | に変更します。

動作の仕組み

• デフォルトでは、OAuth セッションはメモリ内に保存され、再起動すると失われます
• 本番環境では、デプロイやコールドスタート後も認証情報を保持するために、TOKEN_STORE=firestore と JWT_SIGNING_KEY を設定します
• サーバーレスプラットフォーム（Cloud Run など）では、MCP_STATELESS=true を設定します — MCP セッションはメモリ内に保持されるため、ゼロスケールすると失われます。ステートレスモードではセッション追跡が完全に無効になり、各リクエストは JWT/Firestore トークンフローを通じて個別に認証されます
• ALLOWED_DOMAINS は、アクセスを特定の Google Workspace ドメインに制限します
• アクセストークンは自動的に更新されます。非アクティブなセッションは 30 日後に期限切れになります
• ユーザーは Google アカウントの権限 からいつでもアクセスを取り消せます

デプロイメントの更新

main への変更をマージしても、Cloud Run サービスは自動的に更新されません。各デプロイメントは独立しているため、新機能や修正を適用する場合は手動で再デプロイする必要があります。

更新するには：

1. 最新のコードを取得します。

   git pull origin main
   

2. Cloud Run に再デプロイします。

   gcloud run deploy your-service-name --source . --region your-region
   

   既存の環境変数は保持されるため、再度 --set-env-vars を渡す必要はありません。

再デプロイするタイミング：

• バグ修正とセキュリティパッチ — できるだけ早く再デプロイしてください
• 新機能 — 都合のよいタイミングで再デプロイしてください
• 互換性のない変更 — 再デプロイする前にリリースノートを確認してください

リリースページで、現在のバージョンと最新リリースを確認できます。

---

認証オプション

OAuth（デフォルト）

Google Cloud の OAuth クライアント認証情報を環境変数として渡します。

変数	説明
GOOGLE_CLIENT_ID	Google Cloud Console の OAuth クライアント ID
GOOGLE_CLIENT_SECRET	Google Cloud Console の OAuth クライアントシークレット

サービスアカウント（エンタープライズ）

ドメイン全体の委任を使用する Google Workspace の場合：

変数	説明
SERVICE_ACCOUNT_PATH	サービスアカウントの JSON キーファイルのパス
GOOGLE_IMPERSONATE_USER	偽装するユーザーのメールアドレス（任意）

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@a-bonus/google-docs-mcp"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/path/to/service-account-key.json",
        "GOOGLE_IMPERSONATE_USER": "[email protected]"
      }
    }
  }
}

トークンの保存

OAuth のリフレッシュトークンは ~/.config/google-docs-mcp/token.json に保存されます（XDG_CONFIG_HOME に対応）。OAuth クライアント ID とクライアントシークレットはトークンファイルに保存されません。再認証するには、auth コマンドを再度実行するか、トークンファイルを削除してください。

複数の Google アカウント

GOOGLE_MCP_PROFILE を設定すると、トークンをプロフィールごとのサブディレクトリに保存できます。これにより、プロジェクトごとに異なる Google アカウントを使用できます。

変数	説明
GOOGLE_MCP_PROFILE	トークンを個別に保存するためのプロフィール名（任意）

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@a-bonus/google-docs-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "...",
        "GOOGLE_CLIENT_SECRET": "...",
        "GOOGLE_MCP_PROFILE": "work"
      }
    }
  }
}

トークンはプロフィールごとに保存されます。

~/.config/google-docs-mcp/
├── token.json              # default (no profile)
├── work/token.json         # GOOGLE_MCP_PROFILE=work
├── personal/token.json     # GOOGLE_MCP_PROFILE=personal

GOOGLE_MCP_PROFILE を設定しない場合、動作は変わりません。

---

既知の制限事項

• コメントのアンカー設定： プログラムで作成したコメントはコメント一覧に表示されますが、Google Docs の UI ではテキストに明確に紐付けられません。これは Google Drive API の制限です。
• Sheets のコメントのアンカー設定： API で作成したスプレッドシートのコメントにはアンカーのメタデータを保存できますが、Google Workspace のエディタでは Drive API のアンカーはアンカーなしのコメントとして扱われます。対象のセルへのクリック可能なリンクを付けるには createSheetsComment で includeCellLink=true を指定するか、レビュー文をセル自体に添付する必要がある場合は createSheetsCellNote を使用してください。
• コメントの解決： 解決済みのステータスは Google Docs の UI に保持されない場合があります。
• 変換済みのドキュメント： Word から変換したドキュメントでは、すべての API 操作に対応していない場合があります。
• Markdown の画像： Markdown から Docs への変換では、まだサポートされていません。
• 深くネストしたリスト： ネストが 3 階層以上のリストでは、書式に問題が生じる場合があります。
• Gmail の完全削除： trashMessage はメッセージをゴミ箱に移動します（復元可能です）。完全に削除するには、より広い範囲の https://mail.google.com/ スコープが必要ですが、v0.1 では公開されていません。
• Gmail の添付ファイル： getMessage は添付ファイルのメタデータを返しますが、添付ファイルのバイトデータのダウンロードにはまだ対応していません。
• Gmail の HTML メール送信： sendEmail はプレーンテキストのみを送信します。HTML 本文を送信するには、HTML を body フィールドに貼り付けてください。HTML としてレンダリングされず、テキストとして配信されます。
• Calendar のスコープ： calendar.events では既存のカレンダー上のイベントの作成、読み取り、更新、削除ができますが、カレンダー全体の作成や削除はできません。
• Apps Script API はデフォルトで無効です： 各アカウントで一度、https://script.google.com/home/usersettings から有効にする必要があります。ツールで有効にすることはできません。
• Apps Script のデプロイ： ツールではプロジェクトのソースを編集できます。バージョン、デプロイ、インストール型トリガーの作成にはまだ対応していません。onEdit や onOpen などの単純なトリガーは、それらがなくても動作します。
• Calendar の繰り返しイベント： updateEvent と deleteEvent は、listEvents に singleEvents=true を指定して返される特定のインスタンス ID を対象にしない限り、繰り返しイベントのシリーズ全体を変更します。

トラブルシューティング

• サーバーが起動しない場合：
  • MCP 設定の env ブロックで GOOGLE_CLIENT_ID と GOOGLE_CLIENT_SECRET が設定されていることを確認してください。
  • 手動で実行してみてください：npx @a-bonus/google-docs-mcp。標準エラー出力にエラーがないか確認してください。
• 認証エラーの場合：
  • Google Cloud Console で Docs、Sheets、Drive、Gmail、Calendar API が有効になっていることを確認してください。
  • OAuth 同意画面で自分のメールアドレスがテストユーザーとして登録され、必要なスコープ（Docs、Sheets、Drive、gmail.modify、calendar.events）がすべて同意画面に追加されていることを確認してください。
  • 再認証します：npx @a-bonus/google-docs-mcp auth
  • アップグレードする場合は ~/.config/google-docs-mcp/token.json を削除して再認証してください。Gmail と Calendar のスコープは後のバージョンで追加されたため、既存のトークンを更新する必要があります。
  • リモート（Cloud Run）のユーザーは MCP クライアントからサインアウトして再度サインインし、Google が新しいスコープリストで同意を再発行するようにしてください。
• タブのエラーの場合：
  • listTabs を使って、利用可能なタブ ID を確認してください。
  • 単一タブのドキュメントでは tabId を省略してください。
• OAuth サインイン中、claude.ai で「ページが見つかりません」と表示される場合（リモートデプロイ）：
  • 症状：カスタム MCP コネクターで「接続」をクリックすると、Google のサインイン画面ではなく Claude の「ページが見つかりません」ページが表示されます。
  • 原因：Cloud Run のコールドスタートです。アイドル状態のサービスへの最初のリクエストが、コンテナの起動完了前にタイムアウトし、Claude が失敗したリダイレクトを 404 ページに転送します。
  • 回避策：ページを強制再読み込みします（macOS では Cmd+Shift+R、Windows/Linux では Ctrl+Shift+R）。2 回目のリクエストはすでに起動済みのインスタンスに送られるため、OAuth フローが正常に進みます。
  • 恒久的な修正：Cloud Run サービスに --min-instances=1 を設定して、常に 1 つのインスタンスを起動状態に保ちます（gcloud run services update <service> --region <region> --min-instances=1）。メモリ予約の費用は月額約 2～3 ドルです。
• リモートデプロイの再デプロイ後、予期せず再認証が求められる場合：
  • 原因：JWT_SIGNING_KEY はコンテナの起動ごとに自動生成されるため、再デプロイすると、以前に発行されたすべてのセッションが無効になります。
  • 修正：再起動後も維持されるよう、Cloud Run サービスに安定した JWT_SIGNING_KEY 環境変数を設定します：gcloud run services update <service> --region <region> --update-env-vars JWT_SIGNING_KEY=$(openssl rand -hex 32)。この変更後に発行されたセッションは、今後の再デプロイ後も有効です。
• 複数の MCP セッションで CPU 使用率が高い場合： 一部のクライアントは tools/list を非常に頻繁に呼び出します。FastMCP は通常、リクエストのたびにすべてのツールの JSON Schema を再計算するため、プロセスごとに CPU コアを 1 つ占有することがあります。このサーバーは stdio の開始前にペイロードを一度だけ事前計算し、tools/list ハンドラーをキャッシュ済みのスナップショットに置き換えます。それでも負荷が継続する場合は、sample <pid> 1 10（macOS）または node --cpu-prof で数秒間のプロファイルを取得して報告してください。

---

Google Cloud のセットアップ詳細

Google Cloud Console の手順

リモートデプロイの場合は、ウェブアプリケーションタイプの OAuth クライアントを作成してください（デスクトップアプリではありません）。デスクトップアプリは、ローカルでの stdio 使用時のみ選択してください。

1. Google Cloud Console にアクセス： console.cloud.google.com を開きます
2. プロジェクトを作成または選択： プロジェクトのドロップダウン >「新しいプロジェクト」をクリックします。名前（例：「MCP Docs Server」）を入力し、「作成」をクリックします。
3. API を有効化：
   • 「API とサービス」>「ライブラリ」に移動します
   • 次の API を検索して有効にします：Google Docs API、Google Sheets API、Google Drive API、Gmail API、Google Calendar API
4. OAuth 同意画面を設定：
   • 「API とサービス」>「OAuth 同意画面」に移動します
   • 「外部」を選択し、「作成」をクリックします
   • アプリ名、ユーザーサポートのメールアドレス、デベロッパーの連絡先メールアドレスを入力します
   • 「保存して次へ」をクリックします
   • スコープを追加します：documents、spreadsheets、drive、gmail.modify、calendar.events
   • 「保存して次へ」をクリックします
   • テストユーザーとしてご自身の Google メールアドレスを追加します
   • 「保存して次へ」をクリックします
5. 認証情報を作成：
   • 「API とサービス」>「認証情報」に移動します
   • 「+ 認証情報を作成」>「OAuth クライアント ID」をクリックします
   • アプリケーションの種類：「デスクトップアプリ」
   • 「作成」をクリックします
   • クライアント ID と クライアントシークレット をコピーします

---

貢献

貢献を歓迎します！開発環境のセットアップ、アーキテクチャの概要、ガイドラインについては、CONTRIBUTING.md をご覧ください。

ライセンス

MIT -- 詳細は LICENSE をご覧ください。