Google Workspace MCP server

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, a browser, and about ten minutes for npx -y @foreverworks/mcp-google setup, which walks you through the rest: an OAuth client of your own in a free Google Cloud project, made with a few clicks Google lets no program make, and one approval per product and account (what it does). Nothing to set by hand. 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

With Claude Code:

claude mcp add google -- 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"]
    }
  }
}

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:CALENDAR_TIME_ZONE} and so on), so set them before you start Cursor. Every setting is optional; Configuration says which ones you need for which tools.

From a clone

git clone https://github.com/foreverworks/mcps.git && cd mcps
npm ci && npm run build
claude mcp add google -- 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.

Then run setup once, in a terminal, before your first question:

npx -y @foreverworks/mcp-google setup

It asks which products and accounts to connect, opens each Google page you need, picks up the file you download, and has you approve each product in your browser. At the end it prints the command above, with GOOGLE_TOOLSETS added if you chose only some products. Run it again to add an account or a product; it keeps what is already done.

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

Configuration

Nothing needs setting. setup saves the OAuth client and every grant in the server's state directory, ~/.local/state/mcps/google (on Windows %APPDATA%\mcps\google), and the server finds them there. Each grant records the address it was approved as, which is how the server knows which Google account each label stands for. A label is lowercase letters, digits and hyphens (personal, work, client-a), and stands for one Google identity in every product.

The variables below are for a deployment that keeps these files elsewhere, or lists its accounts itself. A variable that is set always wins over what setup saved, and health says where each value came from.

Variable	Required	Meaning
GOOGLE_OAUTH_CLIENT_FILE	no	The OAuth client JSON from the Google Cloud console (a Desktop app client), on which new grants are made. Default: the one setup saved, oauth-client.json in the state directory. Without either, a consent borrows the client of a credentials file the account already has.
GMAIL_ADDRESSES	no	label=address,...: the Google address each account label stands for, in every product. Default: the address each grant recorded. A consent approved as anyone else is refused, and health checks Gmail grants against it.
GMAIL_MODIFY_ACCOUNTS	no	label=path,...: where each mailbox's own gmail.modify grant is kept, which begin_consent writes. Default: every gmail/<label>/credentials.json in the state directory is a mailbox. Set, it lists the mailboxes on its own.
CALENDAR_TIME_ZONE	no	The IANA zone a time without an offset is read in, and working hours default to; default the process's zone (TZ).

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, unless a variable below moves a product's part.

Variable	Meaning
GMAIL_ACCOUNTS	label=path,...: a read-only (gmail.readonly) grant per mailbox, made elsewhere, for instance by a mail-sync program. A mailbox whose gmail.modify grant file does not exist runs on this one: it reads, and every write refuses.
GMAIL_DEFAULT_ACCOUNT	The mailbox a one-mailbox read uses when none is named; default the first listed.
GMAIL_STATE_DIR	Gmail's token caches, <dir>/<label>/; default <GOOGLE_STATE_DIR>/gmail/state.
GMAIL_ATTACHMENTS_DIR	Where attachments are saved, <dir>/<label>/; default attachments/ in each mailbox's state folder.
GMAIL_TIME_ZONE	The zone a reply's "On <date> ... wrote:" line and a forward's Date line are written in, as Gmail writes them in its reader's zone; default CALENDAR_TIME_ZONE, else the process's zone.
CALENDAR_ROOT	Calendar grants, <root>/<label>/credentials.json (written by consent); default <GOOGLE_STATE_DIR>/calendar.
CALENDAR_DEFAULT_ACCOUNT	The account a one-account Calendar read uses; default the first by name.
DRIVE_CREDENTIALS	Drive's one grant (written by consent); default <GOOGLE_STATE_DIR>/drive/credentials.json.
DRIVE_STATE_DIR	Drive's token cache; default <GOOGLE_STATE_DIR>/drive/state.
DRIVE_DOWNLOADS_DIR	Where download_file and download_revision save; default <GOOGLE_STATE_DIR>/drive/downloads.
DRIVE_MIRROR_ROOT	A local copy of My Drive the server may read: upload_file also takes files from it, and sends each to the folder it mirrors.
DRIVE_RCLONE_CONF	An rclone config whose remote's grant Drive borrows until it has its own. The remote must carry its own client_id and client_secret, since rclone's built-in client cannot be refreshed from here. Unset: no rclone.
DRIVE_RCLONE_REMOTE	That remote's name; default gdrive.
GOOGLE_EDITORS_ROOT	Docs, Sheets and Slides grants, <root>/<label>/credentials.json; default <GOOGLE_STATE_DIR>/editors.
GOOGLE_EDITORS_STATE_DIR	Their token caches, <dir>/<label>/, for when the grants must stay read-only; default <root>/<label>/state.
GOOGLE_EDITORS_DRIVE_ACCOUNT	The label whose Docs, Sheets and Slides run on Drive's grant. Unset: none does.
GOOGLE_EDITORS_DEFAULT_ACCOUNT	The account a Docs, Sheets or Slides read uses when none is named; default the one on Drive's grant, else the first.
TASKS_ROOT	Google Tasks grants, <root>/<label>/credentials.json; default <GOOGLE_STATE_DIR>/tasks.
CONTACTS_ROOT	The same for contacts and the directory; default <GOOGLE_STATE_DIR>/contacts.
MEET_ROOT	The same for Meet's records; default <GOOGLE_STATE_DIR>/meet.
GOOGLE_CONSENT_REDIRECT_URI	The loopback address a consent redirects to; default http://localhost:8123/.
GOOGLE_STATE_DIR	The root of all of the above.
GOOGLE_TOOLSETS	The products whose tools the server loads, separated by commas; default every one (Toolsets).

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.

Toolset	What it loads
gmail	Mail: search, read, drafts, sending, labels, filters and attachments.
calendar	Events, free/busy, finding a time, and answering invitations.
drive	Drive's files and folders: paths, changes, upload and download.
docs	Google Docs, simple edits and the full API, with editors_api_reference.
sheets	Google Sheets, rows and ranges and the full API, with editors_api_reference.
slides	Google Slides, decks from an outline and the full API, with editors_api_reference.
collaboration	Comments, sharing and revisions on any Drive file.
tasks	Google Tasks.
contacts	find_people: contacts, saved addresses and a Workspace directory.
meet	Meet's meetings, transcripts and smart notes.

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

The server reaches Google through an OAuth client that belongs to you, in a Google Cloud project of your own. Google's terms do not let a client ship inside an open-source program, so each person makes one. It costs nothing, and your grants then depend on no one else's project.

npx -y @foreverworks/mcp-google setup makes it with you. Run it in a terminal on the computer whose browser you use:

1. Products and accounts. It asks which products to connect (the toolsets) and a label for each Google account, such as personal and work.
2. A project and its APIs. With gcloud installed and signed in, it offers to create the project and enable the APIs itself. Otherwise it opens the console to create a project, then one link that enables every API your products need.
3. Google Auth Platform. Four pages that no program may fill in. Setup opens each one in turn and says what to choose:
   • Branding. On a new project, click Get started, then give an app name only you will see and your address. For an External app, Google also wants an App domain before it lets you publish: setup gives you this server's home page and its privacy policy to paste, with github.com as the authorized domain.
   • Audience. Choose Internal if every account belongs to the Google Workspace organisation that owns the project. Otherwise choose External, then Publish app: Google expires the grants of an app left in Testing after seven days. Only someone holding your client file can ask for an approval, and your own accounts need no verification.
   • Data Access. Setup prints the exact scopes your products ask for, to paste under Manually add scopes.
   • Clients. Create client of type Desktop app, then click Download JSON in the dialog that follows. Google shows the client's secret only there.
4. The client file. Setup watches your Downloads folder for the client_secret_....json you downloaded (or takes a path you type), checks that it is a Desktop app client, and moves it into the state directory, readable only by you.
5. Approvals. For each product and account, setup opens Google's consent page. Choose the account it names. For an External app, Google first warns that it "hasn't verified this app": the app is yours, so click Advanced, then Go to followed by your app's name. Click Continue, tick Select all, and continue again. Google then sends your browser back to setup on 127.0.0.1, which checks the grant and saves it. An account's first approval records its address, and every later one must be approved as that address. If your browser runs on another computer (setup over SSH), the page it lands on fails to load: paste that page's address into setup instead.

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; for an External app, also fill in App domain (a home page and a privacy policy link on an authorized domain), which Google requires before publishing. 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: save it as oauth-client.json in the state directory, or point GOOGLE_OAUTH_CLIENT_FILE at it.

6. Name your accounts, since the server checks each consent against the address of its label, then make each grant from your assistant (First run):

   GMAIL_ADDRESSES=personal=ana@example.com,work=ana@example.org
   

First run

1. Restart your client after adding the server, and ask your assistant for health. Every grant should refresh as the address you meant, with the scopes you ticked, and every API it checks should answer. Under config it says where each setting came from: a variable, or what setup saved.
2. To add a product or an account later, run setup again. Your assistant can also make a grant for an account the server already knows: ask it to "run begin_consent for calendar, account work" (the product is gmail, calendar, drive, editors, tasks, contacts or meet), open the URL it returns, and approve as the address it names. 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, with no restart.

Drive holds one grant: setup asks which account's Drive the Drive tools should reach, and consents drive for that one. That account's Docs, Sheets and Slides can share it (GOOGLE_EDITORS_DRIVE_ACCOUNT=personal); every other account consents editors for its own.

From a shell, npx -y @foreverworks/mcp-google --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. With no product named, it starts with CONFIG: lines saying where each setting came from.

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

Tool	Access	What it does
list_accounts	read	The accounts each product reaches, the default, and which grant each runs on. Start here.
health	read	Per product and account: whether the grant refreshes, which address it resolves to, the scopes Google granted, and, for Docs, Sheets, Slides, Tasks, contacts and Meet, whether the API is enabled.
begin_consent	write	The URL that grants one product access to one account; open it in a browser and approve as the address named.
complete_consent	write	Finishes a consent from the URL the approval redirected to; the grant is checked and saved where the product reads it.