MCP Google Workspace Server

MCP Google Workspace サーバー

Google Workspace サービス向けの Model Context Protocol サーバーです。このサーバーは、MCP プロトコルを通じて Gmail と Google Calendar を操作するツールを提供します。

機能

• 複数の Google アカウントをサポート

  • 複数の Google アカウントを使用し、切り替えられます
  • 各アカウントにカスタムメタデータと説明を設定できます

• Gmail との連携

  • 高度な検索機能でメールを検索します
  • メールの全文と添付ファイルを読み取ります
  • 下書きを作成、管理します
  • メールに返信します
  • メールをアーカイブします
  • 添付ファイルを扱います
  • 一括操作をサポートします

• Calendar との連携

  • 利用可能なカレンダーを一覧表示します
  • カレンダーの予定を表示します
  • 新しい予定を作成します
  • 予定を削除します
  • 複数のカレンダーをサポートします
  • カスタムタイムゾーンをサポートします

プロンプトの例

AI アシスタントで、次のプロンプトを試してみてください。

Gmail

• 「最新の未読メッセージを取得して」
• 「スクラムマスターからのメールを検索して」
• 「経理からのメールをすべて取得して」
• 「ABC についてのメールを取り出して要約して」
• 「Alice の最後のメールに丁寧な返信を書いて、下書きとして保存して」
• 「Bob のメールに感謝の言葉を添えて返信して。下書きとして保存して」

Calendar

• 「明日の予定は何ですか？」
• 「来週の個人アカウントの Family カレンダーを確認して」
• 「来週、Tim と2時間のイベントを計画したいです。時間帯をいくつか提案して」

前提条件

• Node.js >= 20
• Gmail API と Calendar API を有効にした Google Cloud プロジェクト
• Google API 用の OAuth 2.0 認証情報

インストール

1. リポジトリをクローンします。

   git clone https://github.com/j3k0/mcp-google-workspace.git
   cd mcp-google-workspace
   

2. 依存関係をインストールします。

   npm install
   

3. TypeScript コードをビルドします。

   npm run build
   

設定

OAuth 2.0 の設定

Google Workspace（G Suite）API では OAuth2 認証が必要です。認証を設定するには、次の手順に従ってください。

1. OAuth2 認証情報を作成します。

   • Google Cloud Console に移動します
   • 新しいプロジェクトを作成するか、既存のプロジェクトを選択します
   • プロジェクトで Gmail API と Google Calendar API を有効にします
   • 「Credentials」→「Create Credentials」→「OAuth client ID」に移動します
   • アプリケーションの種類として「Desktop app」または「Web application」を選択します
   • 必要な情報を入力して OAuth 同意画面を設定します
   • 承認済みのリダイレクト URI を追加します（ローカル開発では http://localhost:4100/code を含めてください）

2. 必要な OAuth2 スコープ：

   [
     "openid",
     "https://mail.google.com/",
     "https://www.googleapis.com/auth/gmail.settings.basic",
     "https://www.googleapis.com/auth/calendar",
     "https://www.googleapis.com/auth/userinfo.email"
   ]
   

3. Google OAuth 2.0 認証情報を記載した .gauth.json ファイルをプロジェクトのルートに作成します。

   {
     "installed": {
       "client_id": "your_client_id",
       "project_id": "your_project_id",
       "auth_uri": "https://accounts.google.com/o/oauth2/auth",
       "token_uri": "https://oauth2.googleapis.com/token",
       "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
       "client_secret": "your_client_secret",
       "redirect_uris": ["http://localhost:4100/code"]
     }
   }
   

4. サーバーを使用できる Google アカウントを指定する .accounts.json ファイルを作成します。

   {
     "accounts": [
       {
         "email": "[email protected]",
         "account_type": "personal",
         "extra_info": "Primary account with Family Calendar"
       }
     ]
   }
   

   複数のアカウントを指定できます。Google Auth アプリで、それらのアカウントにアクセス権があることを確認してください。extra_info フィールドは特に便利です。ここにアカウントについて AI に伝えたい情報（たとえば、特定のカレンダーがあるかどうか）を追加できます。

認証

.gauth.json と .accounts.json を設定したら、アカウントを認証します。

npm run authenticate

設定した各アカウントについてブラウザーが開き、OAuth 同意フローを完了できます。このスクリプトは、コールバックを最大5分間、アカウントごとに待機します。

# Authenticate a specific account
npm run authenticate -- [email protected]

# Force re-authentication (e.g. after OAuth scope changes)
npm run authenticate -- [email protected] --force

# Custom config paths (same flags as the server)
npm run authenticate -- --gauth-file /path/to/.gauth.json --accounts-file /path/to/.accounts.json

npm からインストールした場合は、次のコマンドも実行できます。

npx mcp-gmail-authenticate

Claude Desktop の設定

mcp-google-workspace サーバーを使用するように Claude Desktop を設定します。

MacOS の場合：~/Library/Application\ Support/Claude/claude_desktop_config.json を編集します

Windows の場合：%APPDATA%/Claude/claude_desktop_config.json を編集します

{
  "mcpServers": {
    "mcp-google-workspace": {
      "command": "<dir_to>/mcp-google-workspace/launch"
    }
  }
}

{
  "mcpServers": {
    "mcp-google-workspace": {
      "command": "npx",
      "args": [
        "mcp-google-workspace"
      ]
    }
  }
}

Docker

MCP サーバーを Docker でビルドして実行することもできます。

docker build -t mcp-google-workspace .
docker run --rm -i \
  -v "$PWD/.gauth.json:/app/.gauth.json:ro" \
  -v "$PWD/.accounts.json:/app/.accounts.json:ro" \
  -v "$PWD/.credentials:/app/.credentials" \
  -e GMAIL_ALLOW_DRAFTS=true \
  -e GMAIL_ATTACHMENTS_DIR=/app/attachments \
  mcp-google-workspace \
  node dist/server.js --credentials-dir /app/.credentials

.gauth.json、.accounts.json、OAuth トークン、.env ファイルをイメージに含めないでください。同梱の .dockerignore でこれらのファイルは除外されています。代わりに、実行時にマウントしてください。

使用方法

1. サーバーを起動します：

   npm start
   

   オプションの引数：

   • --gauth-file：OAuth2 認証情報ファイルへのパス（デフォルト：./.gauth.json）
   • --accounts-file：アカウント設定ファイルへのパス（デフォルト：./.accounts.json）
   • --credentials-dir：OAuth 認証情報を保存するディレクトリ（デフォルト：カレントディレクトリ）

2. サーバーが起動し、stdin/stdout 経由で MCP コマンドを待ち受けます。

3. 各アカウントで初めて実行すると、次の処理が行われます：

   • OAuth2 認証用にブラウザーウィンドウを開きます
   • OAuth2 コールバック用にポート 4100 で待ち受けます
   • 今後の利用に備えて、.oauth2.{email}.json という名前のファイルに認証情報を保存します

環境変数

• GMAIL_ALLOW_SENDING — true に設定すると、gmail_send によるメールの実際の送信が許可されます。デフォルトでは無効です。
• GMAIL_ALLOW_DRAFTS — true に設定すると、下書き作成ツールが許可されます。デフォルトでは無効です。
• GMAIL_ATTACHMENTS_DIR — gmail_get_attachment と gmail_bulk_save_attachments がファイルを書き込めるディレクトリのベースパスです。呼び出し元から指定された添付ファイルのパスは、このディレクトリを基準とする相対パスとして扱われます。絶対パス、ディレクトリ外への遡及、ディレクトリ外へ抜けるシンボリックリンクは拒否されます。デフォルトは ~/.mcp-gsuite/attachments です。

利用可能なツール

アカウント管理

1. gmail_list_accounts / calendar_list_accounts
   • 設定済みのすべての Google アカウントを一覧表示します
   • アカウントのメタデータと説明を確認します
   • user_id は不要です

Gmail ツール

1. gmail_query_emails

   • Gmail の検索構文を使ってメールを検索します（例：'is:unread'、'from:[email protected]'、'newer_than:2d'、'has:attachment'）
   • メールを新しい順に返します
   • メタデータと内容の要約を含みます

2. gmail_get_email

   • ID を指定してメールの全文を取得します
   • メッセージ本文全体と添付ファイル情報を含みます

3. gmail_bulk_get_emails

   • 1 回のリクエストで複数のメールを ID 指定して取得します
   • バッチ処理に効率的です

4. gmail_create_draft

   • 新しいメールの下書きを作成します
   • CC の宛先に対応しています

5. gmail_delete_draft

   • draft_id を指定してメールの下書きを削除します
   • 注意：draft_id は gmail_query_emails が返すメッセージ ID とは異なります。gmail_list_drafts を使って取得してください。

6. gmail_list_drafts

   • Gmail の下書きを一覧表示します。必要に応じて Gmail の検索クエリで絞り込めます
   • 各下書きの draft_id（gmail_delete_draft に必要）と、message_id、件名、宛先、スニペットを返します

7. gmail_reply

   • 既存のメールに返信します
   • すぐに送信するか、下書きとして保存するかを選択できます
   • CC による「全員に返信」に対応しています

8. gmail_get_attachment

   • メールの添付ファイルをダウンロードします
   • ディスクに保存するか、埋め込みリソースとして返します

9. gmail_bulk_save_attachments

   • 1 回の操作で複数の添付ファイルを保存します

10. gmail_archive / gmail_bulk_archive

    • メールを受信トレイから移動します
    • 個別操作と一括操作に対応しています

カレンダーツール

1. calendar_list

   • アクセス可能なすべてのカレンダーを一覧表示します
   • カレンダーのメタデータ、アクセス権限、タイムゾーン情報を含みます

2. calendar_get_events

   • 指定した日付範囲のイベントを取得します
   • 複数のカレンダーに対応しています
   • フィルターオプション（削除済みイベント、最大件数）があります
   • タイムゾーンをカスタマイズできます

3. calendar_create_event

   • 新しいカレンダーイベントを作成します
   • 参加者と通知に対応しています
   • 場所と説明のフィールドがあります
   • タイムゾーンを処理します

4. calendar_delete_event

   • ID を指定してイベントを削除します
   • キャンセル通知を送信するか選択できます

開発

• ソースコードは src/ ディレクトリ内の TypeScript です
• ビルド出力は dist/ ディレクトリに配置されます
• モジュール性を高めるため ES モジュールを使用しています
• Google API のベストプラクティスに従っています

プロジェクト構成

mcp-google-workspace/
├── src/
│   ├── server.ts           # Main server implementation
│   ├── services/
│   │   └── gauth.ts        # Google authentication service
│   ├── tools/
│   │   ├── gmail.ts        # Gmail tools implementation
│   │   └── calendar.ts     # Calendar tools implementation
│   └── types/
│       └── tool-handler.ts # Common types and interfaces
├── .gauth.json             # OAuth2 credentials
├── .accounts.json          # Account configuration
├── package.json            # Project dependencies
└── tsconfig.json           # TypeScript configuration

開発コマンド

• npm run build：TypeScript コードをビルドします
• npm start：サーバーを起動します
• npm run dev：自動リロード付きの開発モードで起動します

貢献

1. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. 変更をコミットします
4. ブランチにプッシュします
5. プルリクエストを作成します

ライセンス

MIT ライセンス。詳細は LICENSE ファイルをご覧ください。