gmail

Gmail Workspace MCP Server

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

機能

• メールの会話を一覧表示：ラベルで絞り込んでメールを取得します
• メールの詳細を取得：本文や添付ファイル情報を含むメールの全内容を取得します
• メールを検索：Gmail の強力なクエリ構文を使って検索します
• メールを管理：既読／未読の切り替え、スターの付与／解除、アーカイブ、ラベルの適用を行います
• 下書きを作成：返信にも対応したメールの下書きを作成します
• メールを送信：新規メールや返信を、直接または下書きから送信します
• 2 種類の認証方法：個人アカウントには OAuth2、Google Workspace にはサービスアカウントを使用します

インストール

npm install gmail-workspace-mcp-server

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

npx gmail-workspace-mcp-server

認証

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

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

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

前提条件

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

更新トークンの取得

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

npx gmail-workspace-mcp-server oauth-setup <client_id> <client_secret>

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

GMAIL_OAUTH_CLIENT_ID=... GMAIL_OAUTH_CLIENT_SECRET=... npx gmail-workspace-mcp-server oauth-setup

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

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

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

これによりブラウザーが開き、Google にサインインすると、更新トークンが表示されます。この手順は一度だけ実行すればよく、更新トークンの有効期限は切れません（OAuth 同意画面が公開されている限り）。

環境変数（OAuth2）

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

Claude Desktop の設定（OAuth2）

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["gmail-workspace-mcp-server"],
      "env": {
        "GMAIL_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GMAIL_OAUTH_CLIENT_SECRET": "your-client-secret",
        "GMAIL_OAUTH_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

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

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

前提条件

1. Google Cloud Console にアクセスします
2. プロジェクトを作成するか、既存のプロジェクトを選択します
3. Gmail API を有効にします
4. ドメイン全体の委任を有効にしたサービスアカウントを作成します
5. Google Workspace Admin Console で、サービスアカウントに次のスコープへのアクセスを許可します：
   • https://www.googleapis.com/auth/gmail.readonly（メールの読み取り）
   • https://www.googleapis.com/auth/gmail.modify（ラベルの変更）
   • https://www.googleapis.com/auth/gmail.compose（下書きの作成）
   • https://www.googleapis.com/auth/gmail.send（メールの送信）
6. JSON キーファイルをダウンロードします

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

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

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

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

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["gmail-workspace-mcp-server"],
      "env": {
        "GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL": "[email protected]",
        "GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----",
        "GMAIL_IMPERSONATE_EMAIL": "[email protected]"
      }
    }
  }
}

注記： 秘密鍵には、次のいずれかを使用できます。

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

ツールグループ

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

グループ	含まれるツール	リスクレベル
readonly	list_email_conversations、get_email_conversation、search_email_conversations、list_draft_emails	低
readwrite	すべての読み取り専用ツール + change_email_conversation、upsert_draft_email	中
readwrite_external	すべての読み書きツール + send_email	高

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

# Read-only access (no write/send capabilities)
GMAIL_ENABLED_TOOLGROUPS=readonly

# Read and write, but no external sending
GMAIL_ENABLED_TOOLGROUPS=readwrite

# Full access including sending emails (default)
GMAIL_ENABLED_TOOLGROUPS=readwrite_external

セキュリティに関する注記： send_email ツールは、外部へのメール送信が可能であり、ラベルの変更や下書きの作成といった内部操作よりもリスクが高いため、別の readwrite_external グループに含まれています。

使用可能なツール

list_email_conversations

任意の条件で絞り込み、Gmail のメールスレッドを一覧表示します。

パラメーター：

• count（数値、任意）：返すメールの数（デフォルト：10、最大：100）
• labels（文字列、任意）：絞り込みに使用するラベル ID のカンマ区切りリスト（デフォルト：「INBOX」）
• sort_by（文字列、任意）：並び順。「recent」（新しい順）または「oldest」（デフォルト：recent）
• after（文字列、任意）：この日時より後のメールのみを返します（指定した日時は含みません。ISO 8601 UTC 形式、例：「2024-01-15T14:30:00Z」）
• before（文字列、任意）：この日時より前のメールのみを返します（指定した日時は含みません。ISO 8601 UTC 形式、例：「2024-01-15T14:30:00Z」）

例：

{
  "count": 20,
  "labels": "INBOX,STARRED",
  "after": "2024-01-15T00:00:00Z",
  "before": "2024-01-20T23:59:59Z"
}

get_email_conversation

ID を指定して、特定のメールの全文を取得します。

パラメーター：

• email_id（文字列、必須）：メールの一意な識別子

例：

{
  "email_id": "18abc123def456"
}

search_email_conversations

Gmail の強力な検索構文を使ってメールを検索します。

パラメーター：

• query（文字列、必須）：Gmail の検索クエリ（例：「from:[email protected]」、「is:unread」、「subject:meeting」）
• count（数値、任意）：返す結果の最大数（デフォルト：10、最大：100）

例：

{
  "query": "from:[email protected] is:unread",
  "count": 20
}

change_email_conversation

メールのラベルとステータス（既読／未読、スター付き、アーカイブ済み）を変更します。

パラメーター：

• email_id（文字列、必須）：変更するメールの ID
• status（文字列、任意）：「read」、「unread」、または「archived」
• is_starred（ブール値、任意）：メールにスターを付ける、または外す
• labels（文字列、任意）：追加するラベルのカンマ区切りリスト
• remove_labels（文字列、任意）：削除するラベルのカンマ区切りリスト

例：

{
  "email_id": "18abc123def456",
  "status": "read",
  "is_starred": true
}

list_draft_emails

Gmail の下書きメールを一覧表示します。スレッドによる絞り込みも指定できます。

パラメーター：

• count（number、任意）：返す下書きの最大数（デフォルト：10、最大：100）
• thread_id（string、任意）：会話のスレッド ID で下書きを絞り込みます

例：

{
  "thread_id": "18abc123def456"
}

upsert_draft_email

下書きメールを作成、更新、または削除します。既存の会話への返信として作成することもできます。

パラメーター：

• draft_id（string、任意）：更新または削除する既存の下書きの ID（新しい下書きを作成する場合は省略します）
• delete（boolean、任意）：true に設定すると、draft_id で指定した下書きを削除します。削除時は、ほかのすべてのパラメーターが無視されます
• to（string、作成／更新時に必須）：宛先メールアドレス
• subject（string、作成／更新時に必須）：メールの件名
• plaintext_body（string）：プレーンテキストの本文（作成／更新時は plaintext_body または html_body の少なくとも一方が必須です）
• html_body（string）：リッチテキスト形式の HTML 本文（作成／更新時は plaintext_body または html_body の少なくとも一方が必須です）
• cc（string、任意）：CC の宛先
• bcc（string、任意）：BCC の宛先
• thread_id（string、任意）：返信先のスレッド ID
• reply_to_email_id（string、任意）：返信先のメール ID（References／In-Reply-To ヘッダーを設定します）

作成／更新時は、plaintext_body または html_body の少なくとも一方を指定する必要があります。両方を指定すると、両方のバージョンを含むマルチパートメールが送信されます。

例（新しい下書きを作成）：

{
  "to": "[email protected]",
  "subject": "Meeting Follow-up",
  "plaintext_body": "Thanks for the meeting today!"
}

例（既存の下書きを更新）：

{
  "draft_id": "r123456789",
  "to": "[email protected]",
  "subject": "Meeting Follow-up (revised)",
  "html_body": "<p>Thanks for the meeting today! Check out <a href=\"https://example.com/notes\">the notes</a>.</p>"
}

例（下書きを削除）：

{
  "draft_id": "r123456789",
  "delete": true
}

send_email

メールを直接送信するか、既存の下書きから送信します。

パラメーター：

• to（string、条件付き）：宛先メールアドレス（下書きから送信する場合を除き必須です）
• subject（string、条件付き）：メールの件名（下書きから送信する場合を除き必須です）
• plaintext_body（string）：プレーンテキストの本文（下書きから送信する場合を除き、plaintext_body または html_body の少なくとも一方が必須です）
• html_body（string）：リッチテキスト形式の HTML 本文（下書きから送信する場合を除き、plaintext_body または html_body の少なくとも一方が必須です）
• cc（string、任意）：CC の宛先
• bcc（string、任意）：BCC の宛先
• from_draft_id（string、任意）：ID で指定した既存の下書きを送信します
• thread_id（string、任意）：返信先のスレッド ID
• reply_to_email_id（string、任意）：返信先のメール ID

例（プレーンテキストメール）：

{
  "to": "[email protected]",
  "subject": "Hello",
  "plaintext_body": "This is a test email."
}

例（HTML メール）：

{
  "to": "[email protected]",
  "subject": "Hello",
  "html_body": "<p>Check out <a href=\"https://example.com\">our website</a> for more details.</p>"
}

例（下書きを送信）：

{
  "from_draft_id": "r123456789"
}

開発

セットアップ

# Install dependencies
npm run install-all

# Build
npm run build

# Run in development mode
npm run dev

テスト

# Run functional tests
npm test

# Run integration tests
npm run test:integration

# Run manual tests (requires credentials)
npm run test:manual

ライセンス

MIT