Google Workspace MCP server

Search, read and organise the mail, calendars, Drive files, Docs, Sheets, Slides, Google Tasks, contacts and Meet transcripts of several Google accounts at once, from your AI assistant. It writes drafts, labels, filters, events, tasks, files, documents, comments and sharing. Nothing is money, and nothing deletes mail or a file for good: Gmail and Drive keep the trash for 30 days.

Mail stays a draft until you say send. Sending, sharing a file and publishing a revision are write tools that tell your assistant to wait for your explicit go. The server does not ask you itself; your client can, before each call. MCP_MAX_ACCESS=read makes the server read-only.

You need one or more Google accounts, your own Google Cloud project with a Desktop app OAuth client (step by step), and a browser to approve each product for each account once. Google expires the grants of an app left in Testing after seven days. The Workspace directory, Meet transcripts and smart notes, and focus time and out of office events need a Google Workspace account.

#What you can ask

• "What's on my calendar this week across both accounts, and does anything clash?"
• "Find 45 minutes with Ana Popescu next week, mornings first."
• "Save every PDF that came to my work mailbox as an attachment in September."
• "Draft a reply to Ana's last email saying Thursday at 10 works. I'll send it myself."
• "Add these invoices to the Invoices sheet, and update any row whose invoice number is already there."
• "What did we decide in yesterday's call with Client SRL? Read me the transcript."

#Install

Install in VS Code Install in Cursor Download for Claude Desktop

With Claude Code:

claude mcp add google -e GOOGLE_OAUTH_CLIENT_FILE="<path to OAuth client file>" -e GMAIL_ADDRESSES="<Accounts and their addresses>" -e GMAIL_MODIFY_ACCOUNTS="<Where Gmail grants are kept>" -- npx -y @foreverworks/mcp-google

Claude Desktop (Settings, Developer, Edit Config) and most other clients read the same command as JSON:

{
  "mcpServers": {
    "google": {
      "command": "npx",
      "args": ["-y", "@foreverworks/mcp-google"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_FILE": "<path to OAuth client file>",
        "GMAIL_ADDRESSES": "<Accounts and their addresses>",
        "GMAIL_MODIFY_ACCOUNTS": "<Where Gmail grants are kept>"
      }
    }
  }
}

Each runs the published package on Node 22.19 or newer. VS Code and the Claude Desktop bundle ask for each setting as they add the server; leave an optional one empty. Cursor reads each from your environment instead (${env:GOOGLE_OAUTH_CLIENT_FILE} and so on), so set them before you start Cursor. The commands above set only what is required; Configuration has the rest.

#From a clone

git clone https://github.com/foreverworks/mcps.git && cd mcps
npm ci && npm run build
claude mcp add google -e GOOGLE_OAUTH_CLIENT_FILE="<path to OAuth client file>" -e GMAIL_ADDRESSES="<Accounts and their addresses>" -e GMAIL_MODIFY_ACCOUNTS="<Where Gmail grants are kept>" -- node "$PWD/servers/google/dist/index.js"

In a JSON configuration, the command is node and its one argument the full path of servers/google/dist/index.js. To share one running copy between several clients over HTTP, see docs/deploying.md.

Over HTTP (MCP_HTTP_PORT), one process serves every session, with one token cache per grant.

#Configuration

The server starts with nothing set: a product not set up yet answers with a config error naming what to set. Four variables cover most setups.

A label is lowercase letters, digits and hyphens (personal, work, client-a), and stands for one Google identity in every product. Everything the server writes (token caches, grants, waiting consents, downloads) goes under GOOGLE_STATE_DIR: by default systemd's STATE_DIRECTORY, else $XDG_STATE_HOME/mcps/google (~/.local/state/mcps/google), unless a variable below moves a product's part.

The variables every server shares (MCP_HTTP_PORT, MCP_MAX_ACCESS, MCP_FILE_ROOTS, MCP_FILE_SCRIPT and the rest) are in docs/configuration.md.

#Toolsets

Every tool definition the server hands your client travels with each request the client makes, so a client that only needs mail and calendars pays for Drive, Docs, Sheets and the rest all the same. GOOGLE_TOOLSETS names the products to load, separated by commas, the way GitHub's MCP server takes GITHUB_TOOLSETS. The tools of a product not loaded are not there at all: not in the tool list, not in the server's instructions, not in list_accounts or health. Unset, empty or all, every product is loaded, as before.

list_accounts, health, begin_consent and complete_consent are always loaded: every other tool takes a label list_accounts names, every remedy points to health, and consent is how any grant is made, including one a loaded product leans on (Meet reads a calendar event through the Calendar grant). A name that is not a toolset stops the server at start, with a message listing the ones there are. Measured with scripts/measure-tokens.ts on 2026-10-23 (GPT-4 tokenizer), the tool list is 115 tools and about 84,800 tokens with every toolset (39,200 without the product icons, which a client may not show the model), 43 tools and 35,600 (16,100) with gmail,calendar, and 46 tools and 32,400 (15,200) with drive,docs,sheets.

To load mail and calendars only, with Claude Code:

claude mcp add google -e GOOGLE_TOOLSETS=gmail,calendar -e GOOGLE_OAUTH_CLIENT_FILE="<path to OAuth client file>" -e GMAIL_ADDRESSES="<Accounts and their addresses>" -e GMAIL_MODIFY_ACCOUNTS="<Where Gmail grants are kept>" -- npx -y @foreverworks/mcp-google

Or in Claude Desktop's configuration:

{
  "mcpServers": {
    "google": {
      "command": "npx",
      "args": ["-y", "@foreverworks/mcp-google"],
      "env": {
        "GOOGLE_TOOLSETS": "gmail,calendar",
        "GOOGLE_OAUTH_CLIENT_FILE": "/path/to/oauth-client.json",
        "GMAIL_ADDRESSES": "personal=ana@example.com,work=ana@example.org",
        "GMAIL_MODIFY_ACCOUNTS": "personal=/path/to/grants/gmail-personal.json,work=/path/to/grants/gmail-work.json"
      }
    }
  }
}

A toolset removes tools; MCP_MAX_ACCESS=read keeps every tool listed and refuses the writes. The shell's --health checks every product whatever GOOGLE_TOOLSETS says; name a product to narrow it.

#Getting the OAuth client

One OAuth client of your own serves every account and product.

1. In the Google Cloud console, create a project for this server.

2. Under APIs & Services, Library, enable the APIs of the products you will use: Gmail API, Google Calendar API, Google Drive API, Google Docs API, Google Sheets API, Google Slides API, Google Tasks API, People API (contacts and the directory) and Google Meet REST API.

3. Open Google Auth Platform. Under Branding, name the app and give your e-mail. Under Audience, pick who may use it, then add every account as a test user or Publish app: Google expires the refresh tokens of an app left in Testing after seven days. A published app can stay unverified for your own accounts; at consent, continue past Google's warning screen.

4. Under Data Access, add the scopes of the products you will use (each is https://www.googleapis.com/auth/ followed by the name below):

   Product	Scopes
   gmail	gmail.modify, and gmail.settings.basic for filters
   calendar	calendar.events, calendar.calendarlist.readonly, calendar.events.freebusy
   drive	drive
   editors (Docs, Sheets, Slides)	documents, spreadsheets, presentations, drive.file
   tasks	tasks
   contacts	contacts.readonly, contacts.other.readonly, and directory.readonly (optional: only a Workspace account has a directory)
   meet	meetings.space.readonly

   Every consent also asks for userinfo.email, so the server can check who approved it.

5. Under Clients, Create client of application type Desktop app, and download its JSON (its installed block holds the client_id and client_secret). Keep the file private, and point GOOGLE_OAUTH_CLIENT_FILE at it.

6. Name your accounts and, for Gmail, where each mailbox's grant goes:

   GMAIL_ADDRESSES=personal=ana@example.com,work=ana@example.org
   GMAIL_MODIFY_ACCOUNTS=personal=/path/to/grants/gmail-personal.json,work=/path/to/grants/gmail-work.json

   Add them to the server's configuration in your client, and restart it.

#First run

Each product needs a grant per account, made once in your browser.

1. Ask your assistant for list_accounts: the labels each product knows (the mailboxes in GMAIL_MODIFY_ACCOUNTS; for other products, the accounts with a grant).
2. Ask it to begin a consent, for instance "Run begin_consent for calendar, account work". The product is gmail, calendar, drive, editors, tasks, contacts or meet.
3. Open the URL it returns, sign in as the address it names, and tick every box. A client with MCP URL elicitation offers you the page itself.
4. The browser then fails to load http://localhost:8123/?state=...&code=..., as expected: nothing listens there. Within 15 minutes, copy the whole address from the address bar and give it to your assistant for complete_consent. The product uses the grant from its next call.
5. Repeat for each product and account. Drive holds one grant: consent drive once, for the account whose Drive the Drive tools should reach. That account's Docs, Sheets and Slides can share it (GOOGLE_EDITORS_DRIVE_ACCOUNT=personal); every other account consents editors for its own.
6. Ask for health. Every grant should refresh as the address you meant, with the scopes you ticked, and every API it checks should answer.

From a shell, node dist/index.js --health [gmail|calendar|drive|editors|tasks|contacts|meet] prints one line per account and grant and exits with the worst line's code, for a timer.

#Tools

read changes nothing in your accounts (the download tools save a local copy); write changes something in one of them. With GOOGLE_TOOLSETS set, only the tables of the toolsets loaded apply; the accounts and consent tools are always there.

Every tool takes account, a label from list_accounts, except Drive's (Drive holds one grant), list_accounts, complete_consent and editors_api_reference. The reads that make sense across accounts (search_threads, agenda, free_busy, find_time, list_calendars, list_tasks, list_task_lists, find_people and health) read every account when none is named; any other read uses the product's default account. A write has no default, because mail or an event made as the wrong identity goes out under that identity.

#Accounts and consent

#Gmail

#Calendar

#Drive

#Comments, sharing and revisions

On any Drive file (a Doc, a Sheet, a deck, a PDF), acting as a Docs, Sheets and Slides account.

#Docs, Sheets and Slides: the API reference

#Docs

#Sheets

#Slides

#Tasks

#Contacts

#Meet

#Troubleshooting

A failure comes back as {"error": {"kind", "message", "remedy"}}, and the remedy names the next step.

config: "credentials at ... are missing or unparseable", "Drive has no grant", or "no calendar grant for "work"" (the same for other products). Run that product's consent for the account (First run); the message lists the accounts that have one.

config: "no address is known for "work"" or ""work" is not a mailbox here". Add work=<address> to GMAIL_ADDRESSES, or work=<path> to GMAIL_MODIFY_ACCOUNTS. "no OAuth client is known" means GOOGLE_OAUTH_CLIENT_FILE is not set.

input: "no consent is waiting for that state". The consent expired after 15 minutes, was already completed, or was begun by a copy of the server with another state directory. Begin again; each consent URL works once.

auth with code wrong_account or insufficient_scope at consent. You approved as another address or left a box unticked; nothing was saved. Begin again as the address named, and tick every box. On a later call, insufficient_scope means the grant lacks what that call needs (filters need gmail.settings.basic): consent the product again.

auth with code readonly_grant. The mailbox runs on a read-only grant from GMAIL_ACCOUNTS, so writes refuse before any request. Consent gmail for it.

auth with code invalid_grant. The refresh token expired or was revoked. Consent the product again; if the app is in Testing, publish it to stop the weekly expiry. A read-only grant from GMAIL_ACCOUNTS is renewed by whatever made it. deleted_client means the OAuth client itself is gone from the Cloud console.

api with reason SERVICE_DISABLED or accessNotConfigured. Enable the API the remedy names in the Cloud project of the grant's OAuth client.

api with status 403 on a file. The account cannot open or change it: check it is shared with that account. On the editors scopes alone, Drive lets the client copy only files it created or opened, so create_deck_from_outline cannot copy a template made by hand; run that account on Drive's grant (GOOGLE_EDITORS_DRIVE_ACCOUNT).

api with reason outcome_unknown. A write failed after it may have reached Google (a dropped connection, a 5xx), so it was not retried. Look first (Sent or Drafts, agenda, list_tasks, read_document, read_rows, read_deck), and repeat it only if it is not there.

api with reason stale_revision. The document changed since it was read: read it again and redo the edit.

api with status 404 from list_history. Gmail expired that historyId: search again with search_threads, and take a new anchor from health.

quota. Google's per-minute quota held through every retry. Wait a minute.

ambiguous, with candidates. Two Drive objects answer to that path. Call again with file_id, one of the ids listed.

#How it works

#Accounts and grants

• One grant per product and account, with its own token cache and only that product's scopes: a Tasks grant cannot read mail, and a Calendar token never reaches Gmail.
• Grants are found, not listed: Calendar, Docs, Sheets and Slides, Tasks, contacts and Meet look for <root>/<label>/credentials.json on every call, so a new consent needs no restart.
• Credentials are google.oauth2 JSON (refresh_token, client_id, client_secret, token_uri, scopes, account). A stored access token is ignored: the server refreshes under a lock, so copies sharing a state directory refresh once.
• A file declares scopes; Google grants them. health reads each grant's real scopes, client and address from Google's tokeninfo, and fails a read-only Gmail grant that has grown a write scope.
• Consent uses PKCE (S256) and prompt=consent (a refresh token every time), with login_hint set to the account's address. A grant approved as another address, missing a required scope, or without a refresh token is refused with nothing written; an optional scope may be left out. Waiting consents and grants are written with mode 0600, a replaced grant is kept as .bak, and no token appears in a result.

#Gmail

• A send is never retried blind: only answers that prove Gmail did not act (429, a rate-limit 403, a 401 before the refresh) are retried. Everything a send depends on is read before it, so a sent mail is never reported as failed.
• Replies look like Gmail's own: the original's markup, an attribution in Gmail's words and the inline images, so Gmail still folds the quote behind "•••". A forward carries the images too.
• Attachments in are byte-exact or refused: a path inside the server's file roots (MCP_FILE_ROOTS), or content_base64 with the source's sha256 from a script, never typed by a model. Capping them at 30 MiB together lets a message slightly over Gmail's 25 MB get Gmail's own refusal, and uploads nothing far beyond it.
• Attachments out are whole or absent. Each part's length is checked against the size Gmail states, and a file never replaces a different one (a second invoice.pdf becomes invoice (2).pdf). Gmail's "download all attachments" zip silently leaves out parts keyed by message id, so harvest_attachments walks each message's MIME tree instead.
• Reads. Bodies are cut at 40,000 characters, and an HTML-only body is converted to text, saying so (bodySource). Gmail links use ?authuser=<address>, because /u/0/ depends on sign-in order.
• Speed. search_threads fetches thread metadata 16 at a time, only the headers a summary reads: Gmail's batch endpoint runs its sub-requests one after another, and measured slower.

#Calendar

Busy time comes from events, not from freebusy.query, which does not accept the calendar.events scope and cannot tell a tentative block or an all-day event's day. One rule (calendar/domain/events.ts) serves the agenda's conflicts, free_busy and find_time:

• One timeline. Overlapping and touching blocks are joined, so a meeting in two accounts counts once. Other people's time (attendees) comes from freebusy.query, asked through every account; someone nobody can see is unknown, never free.
• Time. 2026-09-29 is a whole day, and find_time works one local day at a time, so 09:00 stays 09:00 across a DST change.
• Writes. A series id looks like an occurrence's, so a whole series takes scope: "series". meet: true sends a request id made for that write, so a retry makes one Meet call. Focus time and out of office are checked against Google's rules (primary calendar, not all day, no guests, always busy), and decline nothing unless auto_decline says so: every decline is mail to an organiser.

#Drive

• A path is a query, not an address. A folder can hold two objects of one name: resolve_path reports both ids, and move_file refuses to create such a pair. A name may contain / (Meet writes folders like Weekly sync - 2030/01/15) and is then reachable only by id. Names created on macOS are often stored in NFD, so every lookup asks for both spellings.
• A move is one metadata call. In a synced local copy a Doc is a placeholder file, and moving it there makes the sync replace the Doc with the placeholder.
• Bytes are checked both ways. upload_file compares Drive's own checksum (or the bytes read back) with the source and takes back a difference (a replacement's new revision deleted, a new file trashed); download_file checks before writing anything. A converted upload has no bytes to compare, so the check is that Drive made the Google type asked for.
• Rate limits. Drive reports one as a 403 with a reason, read here as a rate limit, not a permission failure. Its quota is per minute, so a refusal waits at least 22 seconds (in Docs, Sheets and Slides too).

#Docs, Sheets and Slides

The operations (markdown sections, rows keyed by a header, decks from an outline) do the arithmetic that goes wrong (Docs' UTF-16 indices, Sheets' grid coordinates, Slides' object ids) in tested pure functions. The full APIs (get_*, find_in_document, batch_update_*) reach the rest.

• Every write is one request: a Docs or Slides batchUpdate pinned to the revision it was computed from, or a Sheets batchUpdate that applies whole or not at all, never retried once it may have reached Google. A file can be given by its id or its URL.
• Every batch is checked before it is sent against the API's Discovery document, vendored in src/<product>/domain/discovery.json (refresh it with npx tsx scripts/refresh-discovery.ts): kinds, fields, types, enum values, read-only fields and field masks, with the nearest right name for a typo. Every problem comes back in one refusal, and nothing is sent. editors_api_reference reads the same document, so it describes exactly what the check accepts, where a JSON Schema of Sheets' requests alone would load hundreds of kilobytes into every session.
• Docs. get_document shows each element's [startIndex, endIndex), with one U+FFFC per index a non-text element takes. A batch that names an index needs expected_revision (refused if the document moved on) or target_revision (Docs carries the positions over later edits). edit_document_section refuses a section holding what markdown cannot carry (an image, a footnote: read_document counts them as notShown) unless drop_hidden is true. A regex in find_in_document runs in a fresh JavaScript context under a 1.5 second limit, so a backtracking pattern cannot stall the process.
• Sheets. read_rows reads dates in the sheet's time, and a currency cell as {value, amount, formatted}, amount its exact decimal string. Writes take "=..." as a formula, "YYYY-MM-DD" as a date and {"amount": "12.50"} as a number, refused when a double cannot hold it exactly.
• Local images. Docs and Slides insert an image only from a URL they fetch, so each PNG, JPEG or GIF in images (name to file path) goes to the account's Drive, shared by link for the batch, then unshared and trashed whatever the outcome; the result says what became of each copy.
• Developer Preview requests (comments, accepting suggestions) pass the check; Google refuses them unless the Cloud project is in its preview program.

#Tasks, contacts and Meet

• Tasks. A due date is a date: Google Tasks keeps midnight UTC and drops any time. include_completed also shows tasks completed in Google's own apps, which the API otherwise hides.
• Contacts. Results merge by address: contacts first, then the directory, then the addresses Gmail saved. A source an account cannot read is listed under unavailable, never read as nobody.
• Meet. list_meetings finds a calendar event's meeting by its Meet code (read with the account's Calendar grant) and, for one occurrence, the sitting that started within an hour of it. Transcripts and notes are Google Docs, so read_document opens them; get_transcript reads one as [0:12:05] Ana Popescu: ..., naming each speaker from the participants.

The smoke scripts in scripts/ drive the built server (or a running one, with MCP_URL) against real accounts; those that write take SMOKE_ACCOUNT and clean up after themselves.

#Limitations

• No permanent delete of mail or files, only Gmail's and Drive's trash. A draft, label or filter deleted here is gone, though.
• Filters only set labels (no forwarding), and Gmail has no filter update: create the new one, delete the old.
• Drive holds one grant, so the Drive tools reach one account's Drive; other accounts reach their files through the Docs, Sheets, Slides, comment and sharing tools.
• Consent needs a browser, and the redirect address copied back by hand: nothing listens on the loopback port.
• read_doc reads a Sheet as CSV of its first tab (Drive's export has no tab selector); read_rows reads any tab.
• Docs' markdown tools: a bullet under a number comes out as a sub-number (one preset per list), a horizontal rule is dropped, and an image becomes a link.
• What the APIs cannot do at all: insert a horizontal rule or set one list level's glyph in Docs, create a suggestion, anchor an API comment to text in a Doc, add animations in Slides. Apps Script reaches some of these, with its own project and grant.
• Images reach Docs and Slides through a URL Google fetches, so a local file is shared by link on Drive for the seconds a batch takes. Sheets' API inserts no images (an =IMAGE() formula needs a link that stays public).
• Sheets has no conditional write: rows someone inserts between a plan's read and its write shift under it, and the API has no revision pin.
• The schema check knows the API revision this server was built with: a field Google added later is refused, naming that revision, until the Discovery documents are refreshed.
• Tasks have no delete here, a repeating task cannot change lists (Google refuses it), and a due date has no time of day.
• The directory answers only for a Workspace account; a personal account reports it under unavailable.
• Meet keeps records for 30 days, shows only meetings the account took part in or organised, and has transcripts or smart notes only where the meeting turned them on (a Workspace feature).
• Sizes: a message's attachments up to 30 MiB together, a Drive upload or download up to 100 MiB, free_busy and find_time over at most 62 days.

#Other servers for Google Workspace

Searched 2026-10-15. Google runs its own servers, and two community servers are maintained and broad:

• Google's remote MCP servers for Gmail, Drive, Docs, Sheets, Slides, Calendar, Chat, People and Classroom: a developer preview a Google Cloud project must enroll in, over Streamable HTTP, with one OAuth connection per account. They do less: the Gmail server cannot send, download an attachment or sync incrementally; the Drive server cannot move, rename or trash a file; Docs, Sheets and Slides take a raw, unchecked batchUpdate. docs/google-gaps.md compares them tool by tool.
• googleworkspace/cli, Google's command line, has dropped its MCP mode; its Gemini CLI extension gemini-cli-extensions/workspace is a stdio server for one signed-in account.
• workspace-mcp on PyPI: stdio, or Streamable HTTP with OAuth 2.1 for many users; more than 120 tools over twelve products, including Forms, Tasks, Chat, Contacts and Apps Script; each call acts for one account.
• @aaronsb/google-workspace-mcp on npm: stdio, an OAuth token per account on local disk, so several accounts sit side by side; Gmail, Calendar, Drive, Docs, Sheets, Tasks, Meet and Contacts, not Slides.

The community servers reach more products. This one exists for what none of them offers: a mail search, the agenda (with conflicts between accounts) and free/busy read every account in one call, and a write has no default account; Gmail syncs from a historyId; Drive has a change cursor and revisions; and Docs, Sheets and Slides come both as operations and as each API's full batchUpdate, checked against the API's schema before sending, a Docs edit pinned to the revision it was computed from.