Google MCP Server

Minimal MCP server for Gmail + Google Calendar. 10 tools, 2 dependencies, zero bloat.

Built to replace heavy integrations (like Arcade's 7,000+ tool cache) with exactly what you need: read email, send email, manage your calendar.

Tools

Gmail (5)

| Tool | Description | |------|-------------| | gmail_list | List recent emails or search Gmail. Supports standard Gmail search queries (from:, subject:, label:, etc.) | | gmail_read | Read a full email by ID (headers + body) | | gmail_send | Send an email with optional CC and reply threading | | gmail_label | Add or remove labels from an email | | gmail_archive | Archive or trash an email |

Calendar (5)

| Tool | Description | |------|-------------| | calendar_list | List upcoming events (defaults to next 7 days) | | calendar_get | Get details of a specific event | | calendar_create | Create an event with title, time, location, description, and attendees | | calendar_delete | Delete an event | | calendar_freebusy | Find free/busy slots in a time range |

Prerequisites

• Node.js 18+ (ES2022)
• Google Cloud project with Gmail API and Google Calendar API enabled
• OAuth 2.0 credentials (Desktop app type)

Setup

1. Google Cloud Project

1. Go to Google Cloud Console
2. Create a new project (or select an existing one)
3. Enable Gmail API and Google Calendar API:
   • Navigate to APIs & Services → Library
   • Search for each API and click Enable
4. Create OAuth credentials:
   • Navigate to APIs & Services → Credentials
   • Click Create Credentials → OAuth client ID
   • Application type: Desktop app
   • Add authorized redirect URI: http://localhost:3000/callback
   • Copy the Client ID and Client Secret

2. Install & Build

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

3. Environment Variables

Set these environment variables (or configure them in your MCP client):

| Variable | Description | |----------|-------------| | GOOGLE_CLIENT_ID | OAuth 2.0 Client ID from Google Cloud | | GOOGLE_CLIENT_SECRET | OAuth 2.0 Client Secret from Google Cloud |

4. First Run — Authorize

On first launch, the server detects missing auth tokens and starts an OAuth flow:

1. A URL is printed to stderr — open it in a browser
2. Authorize with your Google account
3. The callback is caught on localhost:3000
4. Tokens are saved to ~/.google-mcp/auth.json (chmod 600)

Subsequent launches skip this step — the saved refresh token handles everything.

5. Configure Your AI Agent

OpenClaw

Add to openclaw.json:

{
  "mcpServers": {
    "google-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/google-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "${GOOGLE_CLIENT_ID}",
        "GOOGLE_CLIENT_SECRET": "${GOOGLE_CLIENT_SECRET}"
      }
    }
  }
}

Store the actual values in .openclaw/.env:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

Claude Desktop

Add to claude_desktop_config.json:

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

Any MCP Client

The server communicates over stdio and follows the Model Context Protocol spec. Point your client's MCP config at:

node /path/to/google-mcp/dist/index.js

With env vars GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.

Architecture

AI Agent ← stdio → MCP Server (TypeScript)
                        │
                   Google OAuth2 (refresh tokens)
                        │
                   googleapis (Gmail + Calendar)

• Transport: stdio (standard MCP)
• Auth: OAuth2 with offline access + auto-refresh
• Token storage: ~/.google-mcp/auth.json (chmod 600)
• Rate limit handling: exponential backoff, max 3 retries on 429
• Token refresh: automatic via google-auth-library event listener

OAuth Scopes

https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/gmail.compose
https://www.googleapis.com/auth/calendar.readonly
https://www.googleapis.com/auth/calendar

File Structure

google-mcp/
├── src/
│   ├── index.ts    — MCP server entry + all 10 tools
│   └── auth.ts     — OAuth2 flow + token management
├── dist/           — compiled output
├── package.json
├── tsconfig.json
├── DESIGN.md
└── README.md

Security

• Token file saved with chmod 600
• No credentials in logs or error messages
• No email content leaked in errors
• Only 2 runtime dependencies: @modelcontextprotocol/sdk + googleapis
• OAuth tokens never sent to any third party

Development

# Build
npm run build

# The server runs on stdio — test it directly:
GOOGLE_CLIENT_ID=xxx GOOGLE_CLIENT_SECRET=xxx node dist/index.js

License

MIT