gmail_list_accountsLABSCO SUMMARY
Sending and drafting are off by default, and that is the right default.
An assistant with unrestricted access to your mailbox is a bad first configuration; here reading and searching work immediately while GMAIL_ALLOW_SENDING and GMAIL_ALLOW_DRAFTS stay off until you decide otherwise. The multi-account handling is the other well-judged piece: extra_info on each account is free text the assistant reads, so "check my personal account's family calendar" resolves without you naming the address.
What it is
An MCP server for Gmail and Google Calendar that handles multiple Google accounts at once, each with its own metadata and description so the assistant knows which is which. Gmail tools cover search with Gmail's own query syntax, reading full message bodies, drafts, replies, attachments and archiving, singly and in bulk; Calendar tools cover listing calendars, reading a date range, and creating and deleting events with attendees and timezones.
What you get
- Mail searched with Gmail syntax such as
is:unread,from:,newer_than:andhas:attachment, then read in full singly or in batches —gmail_query_emails,gmail_get_email,gmail_bulk_get_emails - Drafts created, listed and deleted, with the list returning the
draft_idthat deletion needs — it is distinct from the message ID a search returns —gmail_create_draft,gmail_list_drafts,gmail_delete_draft - Replies composed and either sent or saved as a draft, with reply-all through CC —
gmail_reply - Attachments downloaded to disk or returned as an embedded resource, one at a time or in bulk —
gmail_get_attachment,gmail_bulk_save_attachments - Inbox cleanup singly or in bulk —
gmail_archive,gmail_bulk_archive - Calendars listed with access roles and timezone, events read over a date range across several calendars, and events created and deleted with attendees and notifications —
calendar_list,calendar_get_events,calendar_create_event,calendar_delete_event - The configured accounts listed with their metadata, including the free-text
extra_infoyou write to tell the assistant what each account is for —gmail_list_accounts,calendar_list_accounts
Requirements
A Google Cloud project with the Gmail and Calendar APIs enabled and OAuth 2.0 credentials. Node.js >= 20; the published package runs with npx mcp-google-workspace, or build a clone with npm install and npm run build. Two files sit in the server's working folder, or wherever --gauth-file and --accounts-file point: .gauth.json with the OAuth client, and .accounts.json listing which accounts may use the server. Run npx mcp-gmail-authenticate (npm run authenticate in a clone) once per account — it opens a browser, listens on port 4100 for the callback, and stores credentials as .oauth2.{email}.json. The scopes requested are openid, https://mail.google.com/, gmail.settings.basic, calendar and userinfo.email. Three environment variables gate the risky parts. GMAIL_ALLOW_SENDING must be true before gmail_send actually sends and GMAIL_ALLOW_DRAFTS must be true before draft creation works; both default to disabled. GMAIL_ATTACHMENTS_DIR bounds where attachments may be written, rejecting absolute paths, traversal and escaping symlinks, and defaults to ~/.mcp-gsuite/attachments.
Setup effort
Follow the published steps
USE CASES
01
Digging something out of a large mailbox
Search with Gmail's own query syntax, pull the matching messages in bulk, and read the full bodies rather than snippets.
02
Drafting a reply you will send yourself
Let the assistant compose the reply as a draft with reply-all handled, then open Gmail and send it after reading it.
03
Collecting the attachments from a thread
Save several attachments in one operation into the directory you allowed, instead of clicking each one.
04
Finding a slot across two accounts
List the calendars you can reach on each account, then read events over the date range in one call before proposing times.
18 tools
Listed in project docs. Your client may show a different list.
calendar_list_accountsgmail_query_emailsgmail_get_emailgmail_bulk_get_emailsgmail_create_draftgmail_delete_draftgmail_list_draftsgmail_replygmail_sendgmail_get_attachmentgmail_bulk_save_attachmentsgmail_archivegmail_bulk_archivecalendar_listcalendar_get_eventscalendar_create_eventcalendar_delete_eventBEFORE YOU INSTALL
What to know first
Tools you get
18 tools named in the project's documentation.
Requires
- npx on PATH
- Node.js >= 20
Where it runs
The documented client runs the server on your machine.
INSTALLATION
Connect your client
Server setup
In the Google Cloud Console, create or select a project, enable the Gmail API and Google Calendar API, and create an OAuth client ID (Desktop app) with http://localhost:4100/code as an authorized redirect URI
In a folder of your choice, create .gauth.json holding that OAuth client (client_id, client_secret and redirect_uris) and .accounts.json listing the Google accounts that may use the server — the README shows both files
From that folder, authenticate each account once: npx mcp-gmail-authenticate (it opens a browser for each account)
Add the Claude Desktop configuration below
MCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"mcp-google-workspace": {
"command": "npx",
"args": [
"mcp-google-workspace"
]
}
}
}The server reads .gauth.json and .accounts.json, and the tokens mcp-gmail-authenticate saved, from its working folder. Claude Desktop does not start it in your folder, so add "--gauth-file", "--accounts-file" and "--credentials-dir" to args with the full paths of those files and that folder. Sending and draft creation stay off until you set GMAIL_ALLOW_SENDING or GMAIL_ALLOW_DRAFTS to true under env.
