Multi-Gmail MCP Server

A Model Context Protocol (MCP) server that connects your AI assistant to multiple Google accounts simultaneously — Gmail, Calendar, Drive, and Chat — with independent, per-service permission controls (full, read-only, and Gmail's draft-only) for each account.

1. Setup Google Cloud Project

Since this runs locally, you need your own Google Cloud OAuth credentials:

1. Go to the Google Cloud Console.

2. Create a new project (e.g., "Multi-Gmail MCP").

3. Go to APIs & Services > Library and enable the Gmail API, Google Calendar API, Google Drive API, Google Meet API (needed for adding Meet links / Gemini notes to events), Google Chat API, and People API (needed to resolve Chat participant names/emails).

4. Go to APIs & Services > OAuth consent screen:

   • Choose External user type.

   • Fill in the required fields (App name, User support email, Developer contact email).

   • Click Save and Continue until you reach the Test users step.

   • Add the Gmail addresses you plan to connect as test users (required — Google blocks logins for unlisted users).

   • Click Save and Continue.

5. Go to APIs & Services > Credentials:

   • Click Create Credentials > OAuth client ID.

   • Choose Desktop app as the application type.

   • Click Create.

6. Click Download JSON on your new credential.

7. Rename the downloaded file to credentials.json and place it in the project root.

Related MCP server: Gmail MCP Server

2. Install & Build

npm install
npm run build

3. Authenticate Your Accounts

Authorize each Gmail account you want the server to access. Permissions are set per service — Gmail, Calendar, Drive, and Chat can each be configured independently for a single account.

# Full access to everything (default)
npm run auth

# Shorthand: read-only across all services
npm run auth -- --readonly

# Shorthand: Gmail can draft but not send; Calendar/Drive/Chat are read-only
npm run auth -- --draftonly

# Granular: override individual services
npm run auth -- --gmail=<full|draft|readonly> --calendar=<full|readonly> --drive=<full|readonly> --chat=<full|readonly>

Granular flags can combine with the shorthand flags to override just one service, e.g. an account that can never send email but can fully manage your calendar (accept/decline invites, create events):

npm run auth -- --draftonly --calendar=full

This opens a browser window for Google OAuth. Run the command once per account — credentials are saved locally in tokens.json. Re-running the command for an already-authenticated email replaces its stored permissions.

Note: Your Google Cloud project will be in "Testing" status, so Google shows a "Google hasn't verified this app" warning. Click Advanced then Go to [Your App Name] (unsafe) — this is expected since you built the app yourself.

Re-authenticating existing accounts: If an account was authenticated before Calendar/Drive support existed, before the granular per-service permission model, or before space/membership management was added to Chat, its stored scopes may be missing or narrower than what a tool call needs. Re-run npm run auth with the flags for the access you want — Google reuses the same consent flow, so no new credentials are needed. Old tokens.json entries (with the previous readonly/draft_only booleans) still work and are read as their closest equivalent (--readonly → all read-only, --draftonly → Gmail draft-only with Calendar/Drive/Chat read-only) until you re-auth them.

4. Connecting to Claude Desktop

Add the server to your Claude Desktop configuration file.

macOS

Config file location: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "multi_gmail": {
      "command": "node",
      "args": ["/absolute/path/to/multiGoogleMCP/build/index.js"],
      "env": {
        "NODE_PATH": "/absolute/path/to/multiGoogleMCP/node_modules"
      }
    }
  }
}

Windows

Config file location: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "multi_gmail": {
      "command": "node",
      "args": ["C:\\absolute\\path\\to\\multiGoogleMCP\\build\\index.js"],
      "env": {
        "NODE_PATH": "C:\\absolute\\path\\to\\multiGoogleMCP\\node_modules"
      }
    }
  }
}

Replace the paths above with the actual absolute path to your project folder.

After editing the config, restart Claude Desktop for changes to take effect.

5. Connecting to VS Code (Copilot)

Create a .vscode/mcp.json file in your workspace (or add to your user settings):

{
  "servers": {
    "multi_gmail": {
      "command": "node",
      "args": ["/absolute/path/to/multiGoogleMCP/build/index.js"],
      "env": {
        "NODE_PATH": "/absolute/path/to/multiGoogleMCP/node_modules"
      }
    }
  }
}

On Windows, use backslash paths:

{
  "servers": {
    "multi_gmail": {
      "command": "node",
      "args": ["C:\\absolute\\path\\to\\multiGoogleMCP\\build\\index.js"],
      "env": {
        "NODE_PATH": "C:\\absolute\\path\\to\\multiGoogleMCP\\node_modules"
      }
    }
  }
}

VS Code will prompt you to trust the server the first time it starts.

6. Connecting to Google Antigravity

Open the Agent Panel, go to MCP Servers > Manage MCP Servers > Edit configuration to open mcp_config.json, then add:

{
  "mcpServers": {
    "multi_gmail": {
      "command": "node",
      "args": ["/absolute/path/to/multiGoogleMCP/build/index.js"],
      "env": {
        "NODE_PATH": "/absolute/path/to/multiGoogleMCP/node_modules"
      }
    }
  }
}

Use absolute paths. On Windows, use backslash paths (e.g., C:\\Users\\...).

7. Connecting to Cursor

Add a new MCP server in Cursor settings:

• Type: command

• Command: node /absolute/path/to/multiGoogleMCP/build/index.js

If you run into module resolution errors, set the NODE_PATH environment variable to <project-path>/node_modules.

Available Tools

Gmail

Google Calendar

calendar_create_event accepts two optional flags:

Using these requires the Google Meet API to be enabled on your Cloud project (see step 3 above), and the account must be authenticated with calendar=full (the meetings.space.created and meetings.space.settings scopes are bundled into Calendar's full permission tier — re-run npm run auth for accounts authenticated before this was added).

Google Drive

Google Chat

Note: The Chat API does not support arbitrary DM creation via user-authenticated OAuth (it requires resolving Chat user IDs through the People/Admin API). chat_list_spaces already lists existing DM spaces you can send to. chat_create_space creates named spaces (rooms), not 1:1 DMs.

chat_get_attachment metadata (resourceName) comes from the attachments field in chat_list_messages/chat_get_message output — the dedicated attachment-metadata endpoint requires app (bot) authentication and isn't usable here.

Resolving names: When authenticating as a user (as this MCP does), the Chat API only returns an opaque users/{id} for message senders, reaction users, and space members — not their name or email. sender/user/member fields in the tools above are therefore objects ({ name, email }), resolved via a People API lookup on the same numeric ID. Resolution is best-effort: external users or accounts without a visible profile fall back to { name: "users/{id}" } with no email. This requires the People API to be enabled (see step 3) and the directory.readonly scope, bundled into both Chat permission tiers — re-run npm run auth for accounts authenticated before this was added.

Pagination

gmail_search, gmail_list_drafts, drive_list_files, drive_search_files, calendar_list_events, chat_list_spaces, and chat_list_messages accept an optional pageToken parameter and return a nextPageToken field in their JSON response. Pass the returned nextPageToken back in as pageToken to fetch the next page; a null value means there are no more results.

Content Type Support

gmail_draft, gmail_send, and gmail_reply accept an optional contentType parameter:

Example — drafting a Markdown email:

{
  "email": "you@gmail.com",
  "to": "recipient@example.com",
  "subject": "Weekly Update",
  "body": "# Status Report\n\n**Completed:**\n- Feature A\n- Bug fix B\n\n*Next steps:* Feature C",
  "contentType": "markdown"
}

The resulting email renders as formatted HTML in Gmail.