Google Workspace MCP Server

A TypeScript MCP (Model Context Protocol) server that gives Claude read/write access to Google Docs, Sheets, Drive, Calendar, and file comments. Works with Claude Code and Claude Desktop.

27 tools across five services — create, edit, search, and manage your Google Workspace files and events directly from Claude.

Features

Google Docs

• docs_get — Read a document as markdown (headings, bullets, links, tables), optionally with edit indices

• docs_create — Create a new document

• docs_append — Append text to a document

• docs_replace — Find and replace text

• docs_batch_update — Apply raw Docs API requests for formatting and structural edits

• docs_delete — Move a document to trash

Google Sheets

• sheets_get — Read cell values from a range

• sheets_create — Create a new spreadsheet

• sheets_update — Write values to a range

• sheets_append — Append rows to a sheet

• sheets_clear — Clear a range

• sheets_delete — Move a spreadsheet to trash

Google Drive

• drive_list — List files and folders

• drive_search — Search files by name

• drive_get — Get file metadata

• drive_create_folder — Create a folder

• drive_move — Move a file to a different folder

• drive_delete — Move a file to trash

Google Calendar

• calendar_list — List all calendars

• calendar_events — List upcoming events

• calendar_search — Search events by text

• calendar_get — Get full event details

• calendar_create — Create a new event

• calendar_update — Update an existing event

• calendar_delete — Delete an event

Comments (Docs, Sheets, and Slides)

• comments_list — List open comments with their replies (includeResolved to see all)

• comments_get — Get one comment and its full thread

• comments_reply — Reply to a comment, optionally resolving it

Accounts

• authorize — Sign in a Google account (pass account to add another)

• accounts_list — Show authorized accounts and the default

Every other tool takes an optional account argument (an email). Without it, the tool acts as the default account, which is the first one authorized.

Related MCP server: Company MCP Server - Google Workspace Integration

Prerequisites

• Node.js 18 or higher

• A Google Cloud project with OAuth 2.0 credentials

Setup

1. Google Cloud Console

1. Go to console.cloud.google.com

2. Create a new project (or select an existing one)

3. Navigate to APIs & Services → Credentials

4. Click Create Credentials → OAuth Client ID

5. Choose Desktop Application as the application type

6. Download or note the Client ID and Client Secret

Enable the following APIs for your project:

• Google Docs API

• Google Drive API

• Google Sheets API

• Google Calendar API

2. Install and Build

git clone https://github.com/laltaffer/google-workspace-mcp.git
cd google-workspace-mcp
npm install
npm run build

3. Register the server

Claude Code — one command, user scope so it loads in every project:

# macOS: keep the secret out of the config file by storing it in the Keychain
security add-generic-password -s google-workspace-mcp -a client-secret -w your-client-secret

claude mcp add google-workspace --scope user \
  -e GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com \
  -- node /absolute/path/to/google-workspace-mcp/dist/index.js

On other platforms, or if you skip the Keychain step, pass -e GOOGLE_CLIENT_SECRET=your-client-secret as well. Note that claude mcp get prints env values, so prefer the Keychain where available.

Claude Desktop — add the following to your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["/absolute/path/to/google-workspace-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com"
      }
    }
  }
}

Replace /absolute/path/to/google-workspace-mcp with the actual path where you cloned the repo.

Idle exit. The server exits when its client disconnects. Clients that start one server per thread and keep them all running (the Codex app does this) should also set MCP_IDLE_EXIT_MINUTES, for example "30", so idle servers exit instead of accumulating. Add "GOOGLE_CLIENT_SECRET": "your-client-secret" to env only if you did not store the secret in the macOS Keychain.

4. Restart the client

Claude Code picks the server up in new sessions. For Claude Desktop, fully quit and reopen it.

5. Authorize

In a new Claude chat, say:

"Call the authorize tool"

Claude will return a Google authorization URL. Open it in your browser, sign in, and grant access. Your browser will show "Authorization complete!" — you only need to do this once. On macOS, tokens are saved to the Keychain (service google-workspace-mcp, account tokens); elsewhere they are saved to ~/.google-workspace-mcp/tokens.json. Set GOOGLE_WORKSPACE_MCP_TOKEN_STORE=file to force the file store on macOS.

You can now use all Google Workspace tools in Claude.

More than one account. Ask Claude to "authorize laltaffer@example.com" (any email); the tool passes it to Google's account picker. Each account gets its own token, and adding one never signs out another. Then name the account in a request, e.g. "list my Drive files in my work account."

Upgrading? A token stored by an older version is migrated to the multi-account store on first use. If you previously authorized without Calendar support, run the authorize tool again; it detects the stale grant, revokes it, and starts a fresh flow.

Usage Examples

"List my Google Drive files"

"Create a new Google Doc called 'Meeting Notes' and add an agenda"

"Read the spreadsheet with ID 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms and summarize it"

"Find all documents with 'Q1' in the name"

"Append a new row to my budget spreadsheet: ['March', '4500', 'Rent']"

"What's on my calendar this week?"

"Create a meeting called 'Design Review' tomorrow at 2pm for 1 hour"

"What comments are open on the doc with ID 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms?"

Development

npm test          # run tests
npm run test:watch  # watch mode
npm run build     # compile TypeScript

The project uses vitest for testing with mocked googleapis clients, covering auth, accounts, Drive, Docs, Sheets, Calendar, and Comments.

Token Storage

OAuth tokens are stored locally, one per authorized account, in the macOS Keychain or in ~/.google-workspace-mcp/tokens.json on other platforms. An existing tokens file is migrated into the Keychain on first use and then deleted. They are never committed to this repository. To revoke every account, run security delete-generic-password -s google-workspace-mcp -a tokens (or delete the file), or revoke the app in your Google Account security settings.

Tech Stack

• TypeScript

• @modelcontextprotocol/sdk

• googleapis

• zod

• vitest

License

MIT.