Google Workspace MCP Server

Google Workspace MCP サーバー

AI エージェントに Google Workspace への実際のアクセス権を付与 — Gmail、Calendar、Drive、Docs、Sheets、Tasks、Meet、Contacts を、1 つの MCP サーバーから、必要な数のアカウントで利用できます。

メールを検索し、カレンダーを確認し、ドキュメントを作成し、タスクを登録できます — 会話の中で、自分自身として。

インストール

まず、Google OAuth 認証情報が必要です。どの方法を選んでも共通で必要となる唯一の前提条件です。

1. console.cloud.google.com/apis/credentials にアクセスします
2. OAuth 2.0 Client ID を作成し、アプリケーションの種類として Desktop app を選びます
3. 使用する API を有効にします（Gmail、Calendar、Drive、Sheets、Docs、Tasks、Meet — Contacts には People API も必要です。コンソールでは Google がこの名称を使用しています）
4. Client ID と Client Secret を手元に用意します — 後で貼り付けます

次に、自分の作業方法に合った方法を選びます。3 つとも同じサーバーを実行します。

Node 22.12 以降が必要です。（Node 18 と 20 はどちらもサポート終了です。）

---

📦 → 🤖 Claude Desktop — ワンクリック .mcpb インストール（推奨）

最新リリースから google-workspace-mcp.mcpb をダウンロードし、Claude Desktop のウィンドウにドラッグするか、ダブルクリックします。

Claude Desktop に 3 つの項目を含むインストールダイアログが表示されます。

項目
Google OAuth Client ID	必須 — 上記の手順で取得したもの
Google OAuth Client Secret	必須 — 上記の手順で取得したもの
Workspace Directory	任意 — 添付ファイル、ダウンロード、エクスポートの保存先です。既定値は ~/.local/share/google-workspace-mcp/workspace/ です。専用のフォルダーを指定してください。ホーム、Documents、Desktop、Google Drive のフォルダーは指定しないでください。

貼り付けて「保存」を押せば完了です。編集する JSON ファイルも、インストールする Node も、設定するパスもありません — バンドルにはサーバーとすべての依存関係が含まれています。

すべてのプラットフォームで同じバンドルを使えます — macOS（Intel および Apple Silicon）、Linux（x64 および ARM64）、Windows に対応しています。選ぶものはありません。サーバーは純粋な JavaScript で実装されているため、プラットフォーム固有のペイロードを選択する必要はありません。

クロスプラットフォームに関する注意： .mcpb ファイルは Claude Desktop に同梱されたハンドラーを使ってインストールされます。お使いのシステムでダブルクリックしても Claude が起動しない場合は、代わりにファイルを Claude Desktop のウィンドウにドラッグするか、右クリックして「このアプリケーションで開く…」を選び、Claude Desktop を指定してください（OS に選択肢がある場合は「常にこのアプリケーションで開く」も選択します）。動作は環境によって異なります。macOS では通常、自動的に関連付けられます。Windows では初回に関連付けが必要な場合があり、Linux ではデスクトップ環境によって異なります。

---

Claude Code — 1 つのコマンド

claude mcp add google-workspace \
  -e GOOGLE_CLIENT_ID=your-client-id \
  -e GOOGLE_CLIENT_SECRET=your-client-secret \
  -- npx -y @aaronsb/google-workspace-mcp

これで完了です — 編集するファイルはありません。/mcp で確認できます。

---

その他の MCP クライアント

クライアントの MCP 設定ファイルに項目を追加します（Claude Desktop で手動設定する場合は claude_desktop_config.json、Claude Code の場合は .mcp.json）。

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

または、グローバルにインストールして、バイナリを直接指定します。

npm install -g @aaronsb/google-workspace-mcp

仕組み

flowchart LR
    human["🧑 You<br>ask in plain language"]
    agent["🤖 Your AI agent<br>Claude Desktop, Claude Code…"]
    server["⚙️ This MCP server<br>picks the right account,<br>builds the real request"]
    keys[("🔑 Your accounts<br>OAuth tokens, kept<br>on your own machine")]
    google["☁️ Google<br>Gmail · Calendar · Drive · Docs<br>Sheets · Tasks · Meet · Contacts"]

    human -->|"“what's on my calendar?”"| agent
    agent -->|"tool call"| server
    server <-->|"which account?"| keys
    server -->|"real API call, as you"| google
    google -->|"your data"| server
    server -->|"shaped for an agent<br>+ what to do next"| agent
    agent -->|"an answer"| human

    classDef person   fill:#475569,color:#ffffff,stroke:#94a3b8
    classDef robot    fill:#2d7d9a,color:#ffffff,stroke:#4a5568
    classDef ours     fill:#7c3aed,color:#ffffff,stroke:#8b5cf6
    classDef secrets  fill:#2d8e5e,color:#ffffff,stroke:#4a5568
    classDef external fill:#f6821f,color:#1a1a1a,stroke:#d97706

    class human person
    class agent robot
    class server ours
    class keys secrets
    class google external

認証情報がお使いのマシンから外部に送信されることはありません。 サーバーはアカウントごとの OAuth トークンをお使いのディスクに保存し、Google への呼び出しを あなた自身として 行います。仲介サービスも、こちらのアカウントも、登録手続きもありません。必要な数のアカウントを追加できます（個人用と仕事用を並行して利用できます）。サーバーは各リクエストを適切なアカウントに振り分けます。

できること

8 つの Google サービスに対応する 12 個のツールに加え、複数アカウントの処理、アカウントごとの読み取り専用アクセス、一括実行、コンテンツ作成、ファイルサンドボックスを利用できます。

ツール	機能
manage_email	Gmail — 検索、読み取り（プレーンテキストまたはサニタイズ済み HTML）、送信、返信／全員に返信、転送、トリアージ、ゴミ箱への移動、下書き（一覧表示／削除）、ラベル、スレッド、添付ファイル
manage_calendar	Calendar — 一覧表示、予定、取得、作成、quickAdd（自然言語）、更新、削除、カレンダー、空き時間
manage_drive	Drive — 検索、取得、アップロード、ダウンロード、コピー、名前変更／移動、削除、エクスポート、権限、コメント、画像の表示
manage_sheets	Sheets — 範囲の読み取り／書き込み（行番号付きの出力）、追加、クリア、タブの管理、コピー／複製／名前変更
manage_docs	Docs — 取得、作成、追記、テキストの挿入、検索と置換
manage_tasks	Tasks — タスクやタスクリストの一覧表示／作成／更新／完了
manage_meet	Meet — 会議スペースの作成と設定、現在通話中の参加者の確認、過去の会議、参加者、文字起こし、録画、スマートノートの閲覧
manage_contacts	Contacts — 保存した連絡先、やり取りしたことのあるメールアドレス、組織のディレクトリから人物を検索し、連絡先を作成、更新、削除
manage_accounts	複数アカウントのライフサイクル管理 — アカウントの追加、認証情報とスコープの管理
manage_scratchpad	複数行のコンテンツを作成／編集（行または JSON パスで指定）、ファイルを添付し、任意の宛先に送信。JSON モードでは Docs／Sheets とライブ同期
manage_workspace	ワークスペースのサンドボックスでのファイル操作（添付ファイル、ダウンロード、エクスポートの受け渡し場所）
bulk_operations	1 回の呼び出しで複数の処理を実行 — $N.field 参照を使って異なる処理を順番につなぐか、1 回の Google リクエストで同じ処理を複数のリソースに適用します（queue_operations も引き続きエイリアスとして使用できます）

すべての応答には次のステップの案内が含まれるため、エージェントは次に何ができるかを常に把握できます。

1 つの依頼で複数のステップ

便利なのは個々の操作ではなく、エージェントがそれらを連結できることです。

1 つのことを依頼すると、エージェントは 4 つの API 呼び出しを順番に行う必要があると判断し、それぞれの結果を次の呼び出しに渡します。

sequenceDiagram
    autonumber
    participant H as 🧑 You
    participant A as 🤖 Your agent
    participant S as ⚙️ MCP server
    participant G as ☁️ Google

    H->>A: "file the invoice from Acme<br>and remind me to pay it Friday"
    A->>S: find the email
    S->>G: search Gmail
    G-->>S: the message
    S-->>A: found it — and here's what you can do next
    A->>S: save the attachment
    S->>G: download it
    A->>S: put it in Drive
    S->>G: upload
    A->>S: create a task, due Friday
    S->>G: Google Tasks
    A-->>H: Done. Invoice filed, task set for Friday.

これを実現するのは 2 つの機能です。すべての応答でエージェントに次にできることを伝えるため、次のステップを推測する必要がありません。また、bulk_operations を使えば、結果を次々と渡しながら一連の処理を1 回の呼び出しで実行できます。そのため、「請求書を見つけて、ファイルして、リマインダーを設定する」は、4 回ではなく 1 回の往復で済みます。

同じ操作を複数の対象に行う場合は、さらに進んで、それらすべてに対して 1 回の Google リクエストを使用できます。

bulk_operations { mode: 'batch', tool: 'manage_email', operation: 'trash',
                  items: ['msg1', 'msg2', 'msg3', … ] }

200 件のメッセージを 200 回ではなく 1 回の往復でゴミ箱に移動できます。これは意図的に対象を絞っています。Google がそのためのメソッドを公開している場合にのみ動作し、現在は連絡先（作成、更新、削除、取得）と Gmail（ゴミ箱への移動、ラベルの変更）が対象です。それ以外で依頼すると、実行可能な操作が回答に示され、あらゆる場所で利用できる逐次モードに戻るよう案内されます。

不足しているものをリクエストする

このサーバーは95 個の操作を公開しており、Google が公開している 8 つの API の257 個のメソッドのうち 79 個を利用できます。これは意図的に厳選したサブセットです。エージェントはこれらの中から選ぶ必要があり、選択肢に含まれるメソッドはどれも誤って選ぶ可能性があります。257 個の操作を備えたツールが、95 個のツールより高機能とは限りません。正しく使うのが難しくなるだけです。

しかし、その判断はあなた抜きで行われました。

→ Google が公開しているすべてのメソッドを見る

すべてのメソッドを一覧にしています。機能の内容、公開しているかどうか、そして内容があらかじめ入力された issue を開くリクエストリンクを確認できます。説明は Google 独自の文言をそのまま引用しており、クライアントの構築に使うものと同じ仕様からページを生成しているため、実際の状態と食い違うことはありません。

このページには、サーバーがまだ扱っていない3 つの API 全体、Chat、Slides、Forms も掲載しています。同じ理由から、対象にしていないのは自然に決まった事実ではなく、判断の結果です。

良いリクエストでは、メソッドではなくタスクを明示します。

「受信した請求書をエージェントに自動でフォルダーへ振り分けてほしいです。」

これなら検討できます。既存の操作ですでに実現できるかもしれませんし、見つけたメソッドとは別のメソッドが適切だと分かるかもしれません。*「users.settings.filters.create を公開してください」*は結論であって、要望の根拠ではありません。まず問題を伝え、メソッドはそのあとに考えましょう。

なぜオープンコアではなく Apache 2.0 なのか

すべてを公開しています。 有料プランも、「エンタープライズ」版も、あとで販売するために制限した機能もありません。インストールできるものが、そのまま全機能です。

オープンコアは、良い部分を隠して成り立っています。無料のものは見込み客を集めるためのもので、用途が本格化した途端、必要な操作がライセンスの壁の向こう側にあると気づくことになります。このモデルは、ここでは特にひどいものです。これは、あなた自身のデータとあなた自身の Google 認証情報を使い、あなた自身のマシンで動作する、あなたとデータをつなぐ仕組みです。そこに有料の壁を設けるべき理由はなく、ベンダーも必要ありません。

MIT ではなく Apache 2.0 を採用したのは、具体的に 2 つの理由からです。

• 特許の明示的な許諾。 コントリビューターはコードとともに特許請求の権利も許諾するため、後から特許問題になることはありません。MIT では特許について何も定めていないため、問題が解決済みではなく、単に未解決のままです。
• 職場でも安心して採用できます。 Apache 2.0 は、ほぼすべての企業の利用許可リストに含まれています。フォーク、ベンダーへの取り込み、商用製品への組み込みは自由です。誰かに何かを支払う必要も、許可を求める必要もありません。

唯一の義務は、著作権表示をコードとともに維持することです（NOTICE、LICENSE）。それだけです。

v3.0.0 まではこのプロジェクトは MIT ライセンスで、その履歴は消去せずに保持しています。MIT 時代のコントリビューションには元の表示を LICENSE-MIT に残し、その作者は NOTICE に記載しています。Apache 2.0 に移行しても、MIT で認められていたことを取り消すものではありません。

使い方

アカウントを追加します（OAuth のためにブラウザーが開きます）。

manage_accounts { "operation": "authenticate" }

次に、アカウントのメールアドレスを指定して任意のツールを使います。

manage_email    { "operation": "triage", "email": "[email protected]" }
manage_calendar { "operation": "agenda", "email": "[email protected]" }
manage_drive    { "operation": "search", "email": "[email protected]", "query": "quarterly report" }

アカウントに読み取り専用アクセスを付与する

書き込みを絶対に行ってはならないアカウントもあります。同意時に要求する権限を減らせば、トークン自体で送信、編集、削除ができなくなります。これは、広範な権限を持つトークンに後からルールを重ねるものではありません。

manage_accounts { "operation": "scopes", "email": "[email protected]",
                  "services": "gmail,drive,contacts", "access": "read" }

Google には各スコープの読み取り専用版を要求するため、同意画面ですべてのチェックボックスを選んでも、読み取り専用トークンが発行されます。manage_accounts status を実行すると、各アカウントが実際に持つ権限を確認できます。

読み取り専用アカウントからの書き込みは、リクエストが送信される前に拒否されます。アカウント、操作、および元に戻す方法が示されます。

'create' needs write access to contacts. Account [email protected] was authorized
read-only for contacts. Re-authorize with manage_accounts {operation:'scopes',
email:'[email protected]', services:'contacts', access:'readwrite'}, or use an
account that already has it.

読み取り専用スコープがないサービスについては、ブラウザーを開く前に、該当するサービスと、それでも実行できる操作をお知らせします。

複数ステップのワークフロー

結果参照を使って操作を連結できます。あるステップの出力を次のステップに渡します。

{
  "operations": [
    { "tool": "manage_email", "args": { "operation": "search", "email": "[email protected]", "query": "from:boss subject:review" }},
    { "tool": "manage_email", "args": { "operation": "read", "email": "[email protected]", "messageId": "$0.messageId" }}
  ]
}

1 回の操作で複数の対象に対応

Google がその操作のメソッドを公開している場合、複数のリソースに対する同じ操作を 1 回のリクエストで実行できます。

{
  "mode": "batch",
  "tool": "manage_contacts",
  "operation": "delete",
  "email": "[email protected]",
  "items": ["people/c1", "people/c2", "people/c3"]
}

バッチ全体で共通する内容はトップレベルに指定し、items には異なる内容だけを指定します。ID だけが異なる場合は、ID のみで十分です。

データの保存場所

XDG Base Directory Specification に準拠しています。

データ	場所
アカウントレジストリ	~/.config/google-workspace-mcp/accounts.json
認証情報	~/.local/share/google-workspace-mcp/credentials/
ワークスペース（ファイル交換）	~/.local/share/google-workspace-mcp/workspace/

認証情報はアカウントごとのファイルに保存され、標準の OAuth トークンが格納されます。プロジェクトディレクトリにシークレットは保存されません。

内部の仕組み

サーバーを使うために、これらの知識は必要ありません。仕組みに興味がある方や、操作を追加したい方はご覧ください。

サーバーはGoogle 独自の機械可読な API 仕様から Google API クライアントを構築します。手作業で書き起こすことはないため、API の実態とのずれが生じず、操作の追加もコードの変更ではなく YAML の編集で行えます。

• 仕組み — ビルド時と実行時の分担、ディスクリプター、ファクトリー
• API の対応範囲 — 公開されている機能、公開されていない機能、追加を依頼する方法
• API の全体像 — Google が公開しているすべてのメソッドと、まだ対象としていない 3 つの API
• アーキテクチャ上の決定 — ADR。サーバーが Google クライアントを完全に独自で管理する理由も含まれます

ライセンス

Apache License 2.0 — 詳細は上記の「なぜ Apache 2.0 なのか。オープンコアではなく」をご覧ください。