google-workspace-mcp

Why?

Most Google Workspace MCP servers register 30–120 separate tools, each with verbose parameter descriptions that eat thousands of tokens from your LLM context window.

This server takes a different approach:

One tool. One parameter. Full Google Workspace access.

Related MCP server: Google Workspace MCP

⚡ Quick Start

git clone https://github.com/Remenby31/google-workspace-mcp.git
cd google-workspace-mcp
bun install
bun run setup

The interactive wizard handles everything:

1. Asks for your Google Cloud OAuth credentials

2. Writes ~/.mcp.json config automatically

3. Opens your browser for authorization (OAuth 2.1 + PKCE)

4. Verifies the connection by fetching your calendar

Prerequisites: Bun ≥ 1.0 (curl -fsSL https://bun.sh/install | bash) and a Google Cloud project with OAuth credentials.

Add to ~/.mcp.json (or your MCP client's config):

{
  "mcpServers": {
    "google": {
      "command": "bun",
      "args": ["run", "/path/to/google-workspace-mcp/src/index.ts"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_DEFAULT_EMAIL": "you@gmail.com"
      }
    }
  }
}

Claude Code CLI — uses ~/.mcp.json (configured by bun run setup)

VS Code / Cursor — add to .vscode/mcp.json:

{
  "servers": {
    "google": {
      "command": "bun",
      "args": ["run", "/path/to/google-workspace-mcp/src/index.ts"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "...",
        "GOOGLE_OAUTH_CLIENT_SECRET": "...",
        "GOOGLE_DEFAULT_EMAIL": "..."
      }
    }
  }
}

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), same structure as above inside "mcpServers".

🧰 Commands

📅 Calendar

📧 Gmail

📁 Drive

🌐 Options

📋 Output Format

Compact, scannable, token-efficient:

Calendar:

Jun 22 (Mon) — user@company.com
  [a3f2c1] 09:30-10:00  Weekly Standup              📹 meet.google.com/abc-defg-hij
  [b7e4d9] 10:00-10:30  Engineering Sync            📹 meet.google.com/xyz-uvwx-rst
  [——————] all-day       Office

Gmail:

Inbox — user@company.com (3 unread)
  [f8c2a1] Jun 20 14:32  alice@company.com       Re: Deploy pipeline         ★
  [d4e7b3] Jun 19 09:15  bob@company.com         PR Review #432              📎
  [a1b2c3] Jun 18 22:01  noreply@github.com      [proj] CI failed

Drive:

My Drive — user@gmail.com
  📁 [d1e2f3] Projects/          modified Jun 20
  📄 [a4b5c6] Budget 2026.xlsx   12.3 KB  modified Jun 18
  📝 [g7h8i9] Meeting Notes      Google Doc  modified Jun 15

• Short IDs — 6-character codes like [a3f2c1] mapped to full Google IDs within each session. Use them in follow-up commands: cal detail a3f2c1

• Relative dates — today, tomorrow, Mon, Jun 25 instead of ISO timestamps

• Dense layout — one line per item, key info front-loaded, icons for quick scanning

• Truncation — long content truncated with ... to avoid flooding the context

• No boilerplate — no "Successfully retrieved 4 events from calendar 'primary' for user@..." wrappers

🔄 Multi-Account

Connect multiple Google accounts and switch freely:

google cal                              → default account (GOOGLE_DEFAULT_EMAIL)
google cal --as work@company.com        → work calendar
google mail --as personal@gmail.com     → personal inbox

Each account authenticates independently on first use. Tokens are stored per-email in ~/.google-workspace-mcp/credentials/.

🛡️ Error Handling

Errors always include correct syntax and an example — LLMs can self-correct:

> cal create "Meeting" tomorrow
Missing end time. Usage: cal create <title> <start> <end>
Example: cal create "Meeting" "tomorrow 14:00" "tomorrow 15:00"

> mail read
Missing message ID. Run 'mail' or 'mail search <query>' first to get IDs.

> blabla
Unknown command "blabla". Available: cal, mail, drive, help

• Aliases — calendar / agenda / rdv → cal, gmail / email / inbox → mail

• French support — demain, chercher, envoyer, supprimer, lundi

• Flexible dates — tomorrow, next monday, jun 25, 25/06, 2026-06-25

• RSVP tolerance — yes / oui / ok / accepted all work

• Fuzzy actions — read / get / show / view / open all resolve to the same action

🔒 Security

🏗️ Architecture

src/
├── index.ts        MCP server — single tool definition (~50 lines)
├── commands.ts     Command parser, aliases, dispatch
├── auth.ts         OAuth 2.1 + PKCE, token storage, multi-account
├── calendar.ts     Google Calendar API (10 commands)
├── gmail.ts        Gmail API (10 commands)
├── drive.ts        Google Drive API (8 commands)
├── format.ts       Short IDs, relative dates, output formatting
└── setup.ts        Interactive setup wizard

2 runtime dependencies: @modelcontextprotocol/sdk + googleapis

☁️ Google Cloud Setup

1. Go to Google Cloud Console and create a new project

2. Navigate to APIs & Services → Library and enable:

   • Google Calendar API

   • Gmail API

   • Google Drive API

3. Go to APIs & Services → OAuth consent screen:

   • Select External user type

   • Fill in app name and email

   • Publish the app (avoids 7-day token expiry in test mode)

4. Go to APIs & Services → Credentials:

   • Click Create Credentials → OAuth client ID

   • Select Desktop application

   • Copy the Client ID and Client Secret

5. Run bun run setup and paste your credentials

🤝 Contributing

Contributions welcome! The codebase is small (~1,200 lines) and straightforward.

git clone https://github.com/Remenby31/google-workspace-mcp.git
cd google-workspace-mcp
bun install
bun run typecheck    # type checking
bun run test         # run test suite

📄 License

MIT — use it however you want.