multiGmailMCP
One-line summary: multiGmailMCP is an MCP server that connects your AI assistant to multiple Google accounts at once — Gmail, Calendar, Drive, and Chat — with independent per-service permission levels (full, read-only, and Gmail draft-only) for each account.
Gmail — search, read messages and full threads, draft/send/reply/forward (with cc, bcc, attachments, and
text/markdown/htmlbodies), download attachments, send or list drafts, trash/permanently delete, mark read/unread, star/unstar, and manage labels.Google Calendar — list calendars and events (time-range and text filters), get/create/update/delete events, quick-add from natural language, and RSVP (accept/decline/tentative); events can optionally attach a Google Meet link and enable Gemini "take notes" (needs Meet API +
calendar=full).Google Drive — list and search files with Drive query syntax, get metadata, read text (Google Docs/Sheets/Slides auto-exported), download binary as base64, upload files, create folders, trash items, share with users (reader/commenter/writer/owner), and move files between folders.
Google Chat — list/get spaces, create named spaces, list/add/remove members, list/get/send/edit/delete messages (including thread replies), add/list/remove emoji reactions, and download or upload attachments; sender/member names are resolved via People API best-effort.
Multi-account support — every tool takes an
emailparameter so one session can act across several authenticated accounts, with permissions enforced per service per account.Pagination — list/search tools accept
pageToken/maxResultsand returnnextPageTokenfor paging through results.
Allows AI assistants to manage multiple Gmail accounts, including searching, reading, drafting, and sending emails with per-account permission controls (full, read-only, or draft-only).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@multiGmailMCP search for emails from Alice in the last week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
Go to the Google Cloud Console.
Create a new project (e.g., "Multi-Gmail MCP").
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).
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.
Go to APIs & Services > Credentials:
Click Create Credentials > OAuth client ID.
Choose Desktop app as the application type.
Click Create.
Click Download JSON on your new credential.
Rename the downloaded file to
credentials.jsonand place it in the project root.
Related MCP server: Gmail Multi-Inbox MCP Server
2. Install & Build
npm install
npm run build3. 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=fullThis 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 authwith the flags for the access you want — Google reuses the same consent flow, so no new credentials are needed. Oldtokens.jsonentries (with the previousreadonly/draft_onlybooleans) 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:
commandCommand:
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
Tool | Description |
| List all authenticated accounts |
| Search emails using Gmail search operators |
| Read the full content of an email by ID (optional |
| Read all messages in a thread/conversation (optional |
| Create a draft email (supports cc, bcc, attachments) |
| Send an email (supports cc, bcc, attachments) |
| Reply to an email within its thread (send or draft) |
| Forward an email to new recipients |
| Download an attachment from a message |
| Move an email to trash |
| Permanently delete an email |
| Change an email's read state |
| Star or unstar an email |
| List all labels/folders |
| Apply or remove a label from an email |
| List existing draft emails |
| Send a previously saved draft |
Google Calendar
Tool | Description |
| List all calendars in the account |
| List upcoming events, with time range and search filters |
| Get full details of a specific event |
| Create an event (supports attendees, location, all-day, Google Meet, Gemini notes) |
| Update fields on an existing event |
| Delete an event |
| Create an event from natural language text |
| RSVP to an event invitation (accept/decline/tentative) |
calendar_create_event accepts two optional flags:
Flag | Behavior |
| Attaches a Google Meet video conference and returns its join link. |
| Enables Gemini "Take notes for me" auto-generated notes for the Meet space (requires |
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
Tool | Description |
| List files/folders in a given folder (or root) |
| Search using Drive query syntax |
| Get metadata for a file or folder |
| Read text content (exports Google Docs/Sheets/Slides as text) |
| Download binary content as base64 (images, PDFs, zips, etc.) |
| Upload a base64-encoded file |
| Create a new folder |
| Move a file or folder to trash |
| Share a file/folder with another user |
| Move a file/folder to a different parent folder |
Google Chat
Tool | Description |
| List Chat spaces/rooms the account belongs to |
| Get details about a single space |
| Create a new named space, optionally with initial members |
| List the members of a space |
| Add or remove a member from a space |
| List recent messages in a space |
| Get the full content of a single message |
| Send a message to a space (optionally as a thread reply) |
| Edit the text of a message you sent |
| Delete a message you sent |
| Add an emoji reaction to a message |
| List or remove reactions on a message |
| Download an attachment from a message as base64 |
| Upload a file and send it as an attachment, with optional text |
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_spacesalready lists existing DM spaces you can send to.chat_create_spacecreates named spaces (rooms), not 1:1 DMs.
chat_get_attachmentmetadata (resourceName) comes from theattachmentsfield inchat_list_messages/chat_get_messageoutput — 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/memberfields 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 thedirectory.readonlyscope, bundled into both Chat permission tiers — re-runnpm run authfor 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:
Value | Behavior |
| Plain text email |
| Body is converted from Markdown to HTML |
| Body is sent as raw HTML |
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.
Tests
New tests go in packages/core/test/*.cjs and are picked up automatically by npm --prefix packages/core test (no package.json change needed).
Available Tools
54 toolscalendar_create_eventB
Create a new event in a Google Calendar.
Inputs: email (required), title (required), calendarId (required), endDateTime (required), +8 more.
calendar_delete_eventB
Delete a calendar event.
Inputs: email (required), eventId (required), calendarId (required).
calendar_get_eventC
Get details of a specific calendar event.
Inputs: email (required), eventId (required), calendarId (required).
calendar_list_calendarsB
List all calendars in a Google account.
Inputs: email (required).
calendar_list_eventsC
List upcoming events in a calendar.
Inputs: email (required), calendarId (required), query, timeMax, +3 more.
calendar_quick_addB
Create a calendar event from a natural language string (e.g. 'Lunch with John tomorrow at noon').
Inputs: text (required), email (required), calendarId (required).
calendar_respond_to_eventA
RSVP to a calendar event invitation as the authenticated account (accept, decline, or tentative).
Inputs: email (required), eventId (required), calendarId (required), responseStatus (required).
calendar_update_eventC
Update an existing calendar event.
Inputs: email (required), eventId (required), calendarId (required), title, +6 more.
chat_add_memberB
Add a member to a Google Chat space.
Inputs: email (required), spaceName (required), memberEmail (required).
chat_add_reactionB
Add an emoji reaction to a Google Chat message.
Inputs: email (required), emoji (required), messageName (required).
chat_create_spaceA
Create a new named Google Chat space (room), optionally inviting initial members.
Inputs: email (required), displayName (required), memberEmails.
chat_delete_messageB
Delete a Google Chat message you sent.
Inputs: email (required), messageName (required).
chat_get_attachmentA
Download an attachment from a Google Chat message. Use chat_list_messages or chat_get_message first to get the resourceName from the attachments list.
Inputs: email (required), resourceName (required), filename.
chat_get_messageA
Get the full content of a single Google Chat message by its resource name.
Inputs: email (required), messageName (required).
chat_get_spaceB
Get details about a single Google Chat space.
Inputs: email (required), spaceName (required).
chat_list_membersB
List the members of a Google Chat space.
Inputs: email (required), spaceName (required), pageToken, maxResults.
chat_list_messagesB
List recent messages in a Google Chat space.
Inputs: email (required), spaceName (required), pageToken, maxResults.
chat_list_reactionsB
List reactions on a Google Chat message.
Inputs: email (required), messageName (required), pageToken, maxResults.
chat_list_spacesA
List Google Chat spaces (rooms and direct messages) the account belongs to.
Inputs: email (required), pageToken, maxResults.
chat_remove_memberA
Remove a member from a Google Chat space.
Inputs: email (required), spaceName (required), memberEmail (required).
chat_remove_reactionA
Remove a reaction from a Google Chat message. Use chat_list_reactions to get the reaction's resource name.
Inputs: email (required), reactionName (required).
chat_send_messageB
Send a message to a Google Chat space, optionally as a reply within an existing thread.
Inputs: text (required), email (required), spaceName (required), threadName.
chat_update_messageA
Edit the text of a Google Chat message you sent.
Inputs: text (required), email (required), messageName (required).
chat_upload_attachmentB
Upload a file and send it as an attachment to a Google Chat space, with optional accompanying text.
Inputs: data (required), email (required), filename (required), mimeType (required), +3 more.
drive_create_folderB
Create a new folder in Google Drive.
Inputs: name (required), email (required), parentFolderId.
drive_delete_fileA
Delete a file or folder from Google Drive (moves to trash).
Inputs: email (required), fileId (required).
drive_download_fileA
Download a file from Google Drive as base64-encoded binary content. Use for images, PDFs, zips, and other non-text files. Google Docs/Sheets/Slides are exported to a concrete format (default PDF).
Inputs: email (required), fileId (required), exportMimeType.
drive_get_fileA
Get metadata for a specific file or folder in Google Drive.
Inputs: email (required), fileId (required).
drive_list_filesB
List files and folders in Google Drive.
Inputs: email (required), folderId, pageToken, maxResults.
drive_move_fileB
Move a file or folder to a different folder in Google Drive.
Inputs: email (required), fileId (required), newParentFolderId (required).
drive_read_fileA
Read the text content of a file in Google Drive. Works for Google Docs, plain text, and other text-based files.
Inputs: email (required), fileId (required).
drive_search_filesC
Search for files in Google Drive.
Inputs: email (required), query (required), pageToken, maxResults.
drive_upload_fileC
Upload a file to Google Drive.
Inputs: data (required), email (required), filename (required), mimeType (required), +1 more.
gmail_apply_labelA
Apply a label to an email. Use gmail_list_labels to get label IDs.
Inputs: email (required), labelId (required), messageId (required).
gmail_deleteA
Permanently delete an email. This cannot be undone. Use gmail_trash to move to trash instead.
Inputs: email (required), messageId (required).
gmail_draftC
Draft an email using a specific Gmail account.
Inputs: to (required), body (required), email (required), subject (required), +4 more.
gmail_forwardA
Forward an email to new recipients. Use gmail_read first to get the original message content.
Inputs: to (required), body (required), email (required), subject (required), +5 more.
gmail_get_attachmentA
Download an attachment from a Gmail message. Use gmail_read first to get the attachmentId from the attachments list.
Inputs: email (required), messageId (required), attachmentId (required), filename.
gmail_list_accountsA
List all Gmail accounts that are currently authenticated and available for use.
Inputs: no named parameters.
gmail_list_draftsB
List draft emails in a Gmail account.
Inputs: email (required), pageToken, maxResults.
gmail_list_labelsB
List all labels (folders) in a Gmail account.
Inputs: email (required).
gmail_mark_readC
Mark an email as read.
Inputs: email (required), messageId (required).
gmail_mark_unreadB
Mark an email as unread.
Inputs: email (required), messageId (required).
gmail_readA
Read the full content of a specific email by ID.
Inputs: email (required), messageId (required).
gmail_read_threadA
Read all messages in a Gmail thread/conversation in chronological order.
Inputs: email (required), threadId (required).
gmail_remove_labelA
Remove a label from an email. Use gmail_list_labels to get label IDs.
Inputs: email (required), labelId (required), messageId (required).
gmail_replyA
Reply to an email within its existing thread. Use gmail_read to obtain the threadId, messageId (Message-ID header), and references before calling this tool.
Inputs: to (required), body (required), email (required), subject (required), +8 more.
gmail_searchC
Search for emails in a specific Gmail account.
Inputs: email (required), query (required), pageToken, maxResults.
gmail_sendB
Send an email using a specific Gmail account.
Inputs: to (required), body (required), email (required), subject (required), +4 more.
gmail_send_draftA
Send an existing draft email. Use gmail_list_drafts to get draft IDs.
Inputs: email (required), draftId (required).
gmail_starB
Star an email.
Inputs: email (required), messageId (required).
gmail_trashB
Move an email to the trash.
Inputs: email (required), messageId (required).
gmail_unstarA
Remove the star from an email.
Inputs: email (required), messageId (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 54 tools
Tools are clearly separated by domain-specific prefixes (gmail_, calendar_, chat_, drive_), making each tool's purpose immediately identifiable. Within each domain, operations are distinct, and descriptions provide enough detail to differentiate similar actions like gmail_delete vs gmail_trash or gmail_star vs gmail_unstar.
All tool names follow a consistent 'domain_verb_noun' pattern (e.g., gmail_send, calendar_list_events). While verbs like 'read' and 'get' are used for different actions, they are contextually appropriate and not confusing.
With 54 tools, this server is large but justified by covering four distinct Google services. Some tools like gmail_star/unstar or mark_read/unread could be combined, but the count is still reasonable for a comprehensive multi-service MCP.
The tool set provides extensive coverage for Gmail, Calendar, Chat, and Drive, including CRUD operations, search, attachments, and more. Only minor gaps like drive update file exist, but core workflows are fully supported.
Related MCP Connectors
Gmail, Outlook, Drive, OneDrive and calendars for AI agents. Many accounts, one endpoint, audit log.
Every email and calendar account you connect, for AI agents, with permissions and approvals.
Multiple Gmail accounts, editable Google Sheets & Docs for AI agents. Deny-by-default access rules.
Connect Gmail, iCloud Mail, Outlook, Yahoo Mail, Fastmail and other IMAP inboxes to ChatGPT, Claude and compatible AI assistants. Find emails by meaning across languages with semantic search. Ask AI to find customer conversations, summarize deadlines and draft follow-ups. Give a sales rep access to a shared outreach inbox or bring email into a compatible CRM. Share an iCloud custom-domain inbox with teammates without their own Apple ID or iCloud+ plan. Search results may be incomplete or stale; separate permissions control mail actions.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to read, search, organize, and draft emails in Gmail inboxes with support for multiple accounts, OAuth authentication, and 26 comprehensive tools for email management.313 npm3MIT
- AlicenseBqualityBmaintenanceEnables AI assistants to manage multiple Gmail accounts simultaneously with built-in OAuth authentication, supporting email reading, sending, drafts, labels, and account management.605MIT
- FlicenseNot gradedqualityCmaintenanceEnables AI agents to access multiple Gmail/Google Workspace accounts for searching and reading mail, calendars, and attachments.-
- AlicenseNot gradedqualityCmaintenanceConnects Gmail to AI assistants via the MCP protocol, enabling search, read, send, and manage emails across multiple Google accounts simultaneously.MIT