MCP Google Workspace サーバー

Google Workspace サービス用のモデルコンテキストプロトコル（MCP）サーバー。このサーバーは、MCP プロトコルを介して Gmail や Google カレンダーと連携するためのツールを提供します。

特徴

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

  • 複数の Google アカウントの使用と切り替え

  • 各アカウントにはカスタムメタデータと説明を設定できます

• Gmail統合

  • 高度な検索でメールを検索する

  • メールの全文と添付ファイルを読む

  • 下書きの作成と管理

  • メールに返信する

  • メールをアーカイブする

  • ハンドルアタッチメント

  • 一括操作のサポート

• カレンダー統合

  • 利用可能なカレンダーを一覧表示する

  • カレンダーイベントを表示

  • 新しいイベントを作成する

  • イベントを削除する

  • 複数のカレンダーのサポート

  • カスタムタイムゾーンのサポート

Related MCP server: mcp-gsuite

プロンプトの例

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

Gメール

• 「最新の未読メッセージを取得する」

• 「スクラムマスターからのメールを検索する」

• 「経理部からすべてのメールを取得する」

• 「ABCについてのメールを要約してください」

• 「アリスの最後のメールに素敵な返信を書いて、下書きをアップロードしてください」

• 「ボブのメールにお礼のメッセージを添えて返信します。下書きとして保存します。」

カレンダー

• 「明日の予定は何だろう？」

• 「来週の私のプライベートアカウントのファミリー予定を確認してください」

• 「来週、ティムと2時間のイベントを計画する必要があります。時間帯を提案してください。」

前提条件

• Node.js >= 18

• Gmail とカレンダー 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 カレンダー API を有効にする

   • 「認証情報」→「認証情報の作成」→「OAuthクライアントID」に移動します

   • アプリケーションの種類として「デスクトップアプリ」または「Webアプリケーション」を選択します

   • 必要な情報を入力してOAuth同意画面を設定する

   • 承認されたリダイレクト URI を追加します (ローカル開発の場合はhttp://localhost:4100/codeを含めます)

2. 必要な OAuth2 スコープ:

   [
     "openid",
     "https://mail.google.com/",
     "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": "your.email@gmail.com",
         "account_type": "personal",
         "extra_info": "Primary account with Family Calendar"
       }
     ]
   }

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

クロードデスクトップ構成

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

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"
      ]
    }
  }
}

使用法

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という名前のファイルに保存します。

利用可能なツール

アカウント管理

1. gmail_list_accounts / calendar_list_accounts

   • 設定されているすべてのGoogleアカウントを一覧表示する

   • アカウントのメタデータと説明を表示する

   • ユーザーIDは不要です

Gmailツール

1. gmail_query_emails

   • Gmail のクエリ構文を使用してメールを検索します (例: 'is:unread'、'from: example@gmail.com '、'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

   • IDで下書きメールを削除する

6. gmail_reply

   • 既存のメールに返信する

   • すぐに送信するか下書きとして保存するかを選択

   • CC経由の「全員に返信」のサポート

7. gmail_get_attachment

   • メールの添付ファイルをダウンロードする

   • ディスクに保存するか、埋め込みリソースとして返す

8. gmail_bulk_save_attachments

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

9. gmail_archive / gmail_bulk_archive

   • 受信トレイからメールを移動する

   • 個別または一括操作のサポート

カレンダーツール

1. calendar_list

   • アクセス可能なすべてのカレンダーを一覧表示する

   • カレンダーのメタデータ、アクセスロール、タイムゾーン情報が含まれます

2. calendar_get_events

   • 日付範囲内のイベントを取得する

   • 複数のカレンダーのサポート

   • フィルター オプション (削除されたイベント、最大結果)

   • タイムゾーンのカスタマイズ

3. calendar_create_event

   • 新しいカレンダーイベントを作成する

   • 出席者と通知のサポート

   • 場所と説明フィールド

   • タイムゾーンの処理

4. calendar_delete_event

   • IDでイベントを削除する

   • キャンセル通知のオプション

発達

• ソースコードはTypeScriptでsrc/ディレクトリにあります

• ビルド出力は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ファイルを参照