gmail-multi-mcp-server

複数のGmailアカウントを同時にClaudeに接続するMCPサーバーで、組み込みのGmailコネクタと同じツール一式を公開します。すべてのツールは、操作対象のメールボックスを指定する追加の account 引数を受け取ります。これが単一メールボックス用コネクタとの唯一の構造上の違いです。

"Check my work inbox for anything from the lender, and draft the reply from my personal account."

存在理由

組み込みのGmailコネクタは1つのメールボックスのみを認証します。仕事用、個人用、会社のエイリアスなど、複数のアカウントを使い分けている場合、そのたびに切り替える必要があります。このサーバーは、認証したすべてのGmailアカウントの認証情報を保持し、各呼び出しを指定したアカウントにルーティングします。

Related MCP server: multiGmailMCP

要件

• Node.js 20以降

• Gmail APIを有効にしたGoogle Cloudプロジェクトと、デスクトップ アプリ タイプのOAuthクライアント

1. Google OAuthクライアントを取得する

1. Google Cloud Console を開き、プロジェクトを選択または作成します。

2. API とサービス → ライブラリ → で Gmail API を有効にします。

3. API とサービス → OAuth 同意画面 → で設定します。アプリが テスト 状態の間は、接続予定のすべての Gmailアドレスを テストユーザー に追加してください。

4. API とサービス → 認証情報 → 認証情報を作成 → OAuth クライアント ID → でアプリケーションの種類を デスクトップ アプリ にします。JSONをダウンロードします。

デスクトップアプリのクライアントは任意のポートでのループバックリダイレクトを許可します。add-account フローはこれを利用します。

2. インストールとビルド

git clone <this repo>
cd Gmail-MCP
npm install
npm run build

3. サーバーにOAuthクライアントを指定する

いずれかを選択します:

# Option A — save the downloaded JSON where the server looks by default
mkdir -p ~/.gmail-mcp && cp ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json

# Option B — point at it explicitly
export GMAIL_MCP_CREDENTIALS=/path/to/client_secret.json

# Option C — pass the values directly
export GMAIL_MCP_CLIENT_ID=...apps.googleusercontent.com
export GMAIL_MCP_CLIENT_SECRET=...

4. 各メールボックスを認証する

Gmailアカウントごとに1回実行します:

node dist/index.js add-account --alias work
node dist/index.js add-account --alias personal
node dist/index.js list-accounts

実行するたびにGoogleの同意URLが表示され、ローカルのループバックポートでリダイレクトを待機して、取得したリフレッシュトークンを保存します。ヘッドレスマシンでは --manual を追加し、リダイレクト先のURLを貼り付けます。

サーバー実行中に追加されたアカウントは自動的に認識されます。再起動は不要です。

5. Claudeに接続する

Claude Code

claude mcp add gmail-multi -- node /absolute/path/to/Gmail-MCP/dist/index.js

Claude Desktop — claude_desktop_config.json に追加します:

{
  "mcpServers": {
    "gmail-multi": {
      "command": "node",
      "args": ["/absolute/path/to/Gmail-MCP/dist/index.js"],
      "env": {
        "GMAIL_MCP_CREDENTIALS": "/absolute/path/to/client_secret.json"
      }
    }
  }
}

アカウントの選択

list_accounts を除くすべてのツールは account を受け取ります。次の順序で照合されます:

1. 完全なメールアドレス — mikael@example.com

2. add-account 時に設定したエイリアス — work

3. @ より前のローカル部分 — mikael

4. 一意に特定できる接頭辞

account は、メールボックスが1つだけ設定されている場合、または GMAIL_MCP_DEFAULT_ACCOUNT が設定されている場合は省略可能です。それ以外の場合は必須で、エラーには利用可能なアカウントが一覧表示されます。

IDはメールボックスごとに独立しています。 あるアカウントのメッセージ、スレッド、下書き、ラベルのIDは、別のアカウントでは意味をなしません。「見つかりません」というエラーは、通常、誤った account が渡されたことを意味します。

ツール

35個のツール — コネクタのツール一式に、マルチアカウント用の2つを加えた構成です。

ツール名は意図的にGmailコネクタのものと一致させており、プロンプトや操作習慣をそのまま引き継げます。MCPクライアントはツールをサーバーごとに名前空間で区別するため、両方を同時に有効にしても衝突しません。

組み込みコネクタとの違い

以下はすべて追加分です。コネクタの既存の動作が変わることはありません。

• すべてのツールに account が付き、さらに list_accounts と get_profile が追加されます。

• すべてのツールに response_format (markdown | json) が付きます。デフォルトの markdown はコンパクトなままで、どちらの場合も完全な構造化ペイロードは structuredContent として返されます。

• コネクタが参照しているものの公開していない delete_draft と get_message_attachment を追加します。

• reply は quoteOriginal (デフォルト false) を受け取り、元のメッセージを引用ブロックとして末尾に追加します。

• forward は includeAttachments (デフォルト true) を受け取ります。大きなファイルを省略するには false に設定します。

• get_message_attachment は savePath を受け取り、base64をインライン展開する代わりにファイルをディスクへ書き出せます。

• レスポンスは25,000文字に制限され、まずページ分割されたリストを縮小し、何が削除されたか、残りを取得する方法を正確に示します。

Hmm, I need to be very careful with typos. Let me restart the final output and type carefully, checking each Japanese word.

Actually, let me just write the final answer cleanly now, carefully.# gmail-multi-mcp-server

複数のGmailアカウントを同時にClaudeに接続するMCPサーバーで、組み込みのGmailコネクタと同じツール一式を公開します。すべてのツールは、操作対象のメールボックスを指定する追加の account 引数を受け取ります。これが単一メールボックス用コネクタとの唯一の構造上の違いです。

"Check my work inbox for anything from the lender, and draft the reply from my personal account."

存在理由

組み込みのGmailコネクタは1つのメールボックスのみを認証します。仕事用、個人用、会社のエイリアスなど、複数のアカウントを使い分けている場合、そのたびに切り替える必要があります。このサーバーは、認証したすべてのGmailアカウントの認証情報を保持し、各呼び出しを指定したアカウントにルーティングします。

要件

• Node.js 20以降

• Gmail APIを有効にしたGoogle Cloudプロジェクトと、デスクトップ アプリ タイプのOAuthクライアント

1. Google OAuthクライアントを取得する

1. Google Cloud Console を開き、プロジェクトを選択または作成します。

2. API とサービス → ライブラリ → で Gmail API を有効にします。

3. API とサービス → OAuth 同意画面 → で設定します。アプリが テスト 状態の間は、接続予定のすべての Gmailアドレスを テストユーザー に追加してください。

4. API とサービス → 認証情報 → 認証情報を作成 → OAuth クライアント ID → でアプリケーションの種類を デスクトップ アプリ にします。JSONをダウンロードします。

デスクトップアプリのクライアントは任意のポートでのループバックリダイレクトを許可します。add-account フローはこれを利用します。

2. インストールとビルド

git clone <this repo>
cd Gmail-MCP
npm install
npm run build

3. サーババーにOAuthクライアントを指定する

いずれかを選択します:

# Option A — save the downloaded JSON where the server looks by default
mkdir -p ~/.gmail-mcp && cp ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json

# Option B — point at it explicitly
export GMAIL_MCP_CREDENTIALS=/path/to/client_secret.json

# Option C — pass the values directly
export GMAIL_MCP_CLIENT_ID=...apps.googleusercontent.com
export GMAIL_MCP_CLIENT_SECRET=...

4. 各メールボックスを認証する

Gmailアカウントごとに1回実行します:

node dist/index.js add-account --alias work
node dist/index.js add-account --alias personal
node dist/index.js list-accounts

実行するたびにGoogleの同意URLが表示され、ローカルのループバックポートでリダイレクトを待機して、取得したリフレッシュトークンを保存します。ヘッドレスマシンでは --manual を追加し、リダイレクト先のURLを貼り付けます。

サーバー実行中に追加されたアカウントは自動的に認識されます。再起動は不要です。

5. Claudeに接続する

Claude Code

claude mcp add gmail-multi -- node /absolute/path/to/Gmail-MCP/dist/index.js

Claude Desktop — claude_desktop_config.json に追加します:

{
  "mcpServers": {
    "gmail-multi": {
      "command": "node",
      "args": ["/absolute/path/to/Gmail-MCP/dist/index.js"],
      "env": {
        "GMAIL_MCP_CREDENTIALS": "/absolute/path/to/client_secret.json"
      }
    }
  }
}

アカウントの選択

list_accounts を除くすべてのツールは account を受け取ります。次の順序で照合されます:

1. 完全なメールアドレス — mikael@example.com

2. add-account 時に設定したエイリアス — work

3. @ より前のローカル部分 — mikael

4. 一意に特定できる接頭辞

account は、メールボックスが1つだけ設定されている場合、または GMAIL_MCP_DEFAULT_ACCOUNT が設定されている場合は省略可能です。それ以外の場合は必須で、エラーには利用可能なアカウントが一覧表示されます。

IDはメールボックスごとに独立しています。 あるアカウントのメッセージ、スレッド、下書き、ラベルのIDは、別のアカウントでは意味をなしません。「見つかりません」というエラーは、通常、誤った account が渡されたことを意味します。

ツール

35個のツール — コネクタのツール一式に、マルチアカウント用の2つを加えた構成です。

ツール名は意図的にGmailコネクタのものと一致させており、プロンプトや操作習慣をそのまま引き継げます。MCPクライアントはツールをサーバーごとに名前空間で区別するため、両方を同時に有効にしても衝突しません。

組み込みコネクタとの違い

以下はすべて追加分です。コネクタの既存の動作が変わることはありません。

• すべてのツールに account が付き、さらに list_accounts と get_profile が追加されます。

• すべてのツールに response_format (markdown | json) が付きます。デフォルトの markdown はコンパクトなままで、どちらの場合も完全な構造化ペイロードは structuredContent として返されます。

• コネクタが参照しているものの公開していない delete_draft と get_message_attachment を追加します。

• reply は quoteOriginal (デフォルト false) を受け取り、元のメッセージを引用ブロックとして末尾に追加します。

• forward は includeAttachments (デフォルト true) を受け取ります。大きなファイルを省略するには false に設定します。

• get_message_attachment は savePath を受け取り、base64をインライン展開する代わりにファイルをディスクへ書き出せます。

• レスポンスは25,000文字に制限され、まずページ分割されたリストを縮小し、何が削除されたか、残りを取得する方法を正確に示します。

知っておくと役立つ動作

• search_threads は、コネクタと同様に、各スレッドの最古のメッセージのプレビュー (~5件) を返します。最近のメールや未読メールについて回答する前に get_thread を呼び出してください。

• クエリが下書きに言及している場合を除き、下書きは search_threads から除外されます。list_drafts を使用してください。

• ラベルは表示名ではなくIDで指定します。最初に list_labels を呼び出してください。

• DRAFT と SENT は読み取り専用です。TRASH/SPAM の追加は apply_sensitive_* ツールにルーティングされ、破壊的な操作が常に明示的に指定されます。

• update_draft はフィールドをマージしますが、添付ファイルはマージではなく置き換え られます。レスポンスには破棄された件数が報告されます。

• reply は In-Reply-To と References を設定してクライアントが正しくスレッドを組めるようにし、返信を認証済みメールボックス自身に宛てることは決してありません。

セキュリティ

• リフレッシュトークンは ~/.gmail-mcp/accounts.json に保存され、0700 ディレクトリ内に 0600 のパーミッションでアトミックに書き込まれます。このファイルの読み取り権限を持つ者は、メールボックスへの完全なアクセス権を得ることになります。

• OAuthフローは state パラメータを検証し、127.0.0.1 のみで待ち受けます。

• remove-account はローカルのトークンを削除します。完全に取り消すには、myaccount.google.com/permissions でアプリも削除してください。

• 付与されたスコープでは、メールの読み取り、送信、削除が許可されます。send_message、reply、forward は即座に配信されます。ツールの説明では、ユーザーが明確に送信を求めていない場合は create_draft を優先するようモデルに指示しています。

開発

npm run build         # compile TypeScript to dist/
npm test              # build, then unit tests + stdio smoke test
npm run test:unit     # MIME, reply addressing, parsing, truncation — no network
npm run test:smoke    # boots the server, checks all 35 tools register
npm run inspect       # open the MCP Inspector against the server

src/
  index.ts            CLI entry point and server bootstrap
  constants.ts        scopes, limits, paths
  types.ts            normalized message/thread/draft shapes
  auth/               token store, OAuth flow, account registry
  schemas/common.ts   shared Zod fields (account, formats, pagination, colors)
  services/           Gmail parsing, MIME building, formatting, errors
  tools/              tool registration by domain

トラブルシューティング

ライセンス

MIT