Google Workspace

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.

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.

Every other variable (all optional)

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 calend