mcp-gsuite

MCPize

A Model Context Protocol (MCP) server for interacting with Google Workspace — Gmail & Google Calendar — via a streamable HTTP transport. Built with TypeScript, Express, and the official Google APIs Node.js client.

Features

📧 Gmail — list, search, send, and label emails
📅 Google Calendar — list, create, update, and delete events
🔐 OAuth 2.0 — offline access via refresh tokens (no re-auth needed)
⚡ Stateful sessions — each MCP client gets its own isolated session
🐳 Docker-ready — includes a production-grade Dockerfile
☁️ Cloud Run compatible — graceful SIGTERM/SIGINT shutdown handling

Quick Start

npm install
npm run dev     # Start with hot reload (tsx watch)

Local development:

MCP endpoint: http://localhost:8080/mcp
Health check: http://localhost:8080/health

Remote (MCPize hosted):

MCP endpoint: https://mcp-gsuite.mcpize.run/mcp

Prerequisites

A Google Cloud project with the following APIs enabled:
- Gmail API
- Google Calendar API
OAuth 2.0 Web Application credentials — download as credentials.json from Google Cloud Console
A refresh token for offline access (see below)

credentials.json format

{
  "web": {
    "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uris": [
      "https://your-deployed-url/mcp",
      "http://localhost:4100/mcp"
    ],
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token"
  }
}

Getting a Refresh Token

npm run generate    # Automated OAuth flow (recommended)
# or
node get-refresh-token.js

The script will open a browser for Google sign-in and save the token to .env automatically.

Environment Variables

Copy .env.example to .env and fill in:

cp .env.example .env

Variable	Description	Required
`GOOGLE_CLIENT_ID`	OAuth client ID from Google Cloud Console	✅
`GOOGLE_CLIENT_SECRET`	OAuth client secret	✅
`GOOGLE_REFRESH_TOKEN`	Refresh token for offline access	✅
`PORT`	Server port (default: `8080`)	❌
`NODE_ENV`	Set to `production` to disable dev logging	❌

Note: The server will throw an error on startup if any of the three required credentials are missing.

Development

npm install         # Install dependencies
npm run dev         # Development mode with hot reload (tsx watch)
npm run build       # Compile TypeScript to dist/
npm start           # Run compiled server (node dist/index.js)
npm test            # Run unit tests (vitest)
npm run test:smoke  # Run smoke/connectivity test

Project Structure

├── src/
│   └── index.ts                # MCP server — all tool handlers & Express setup
├── tests/
│   └── tools.test.ts           # Vitest unit tests
├── scripts/
│   ├── list-events.mjs         # Standalone calendar event listing script
│   └── smoke-test.js           # Basic connectivity smoke test
├── get-refresh-token.js        # Automated OAuth flow helper
├── credentials.json            # Google OAuth client credentials (not committed)
├── token.json                  # Cached OAuth tokens (auto-generated, not committed)
├── package.json                # Dependencies and npm scripts
├── tsconfig.json               # TypeScript compiler configuration
├── mcpize.yaml                 # MCPize deployment manifest
├── Dockerfile                  # Container build instructions
├── .env                        # Your local secrets (not committed)
└── .env.example                # Environment variables template

MCP Tools

📧 Gmail

Tool	Description	Key Parameters
`list_emails`	List recent emails from Gmail inbox	`maxResults` (1–500, default 10), `query` (Gmail filter)
`search_emails`	Search emails with Gmail query syntax	`query` (required), `maxResults` (1–500, default 10)
`send_email`	Send an email (plain text + HTML)	`to`, `subject`, `body`, `cc?`, `bcc?`
`modify_email`	Add or remove Gmail labels on a message	`id`, `addLabels[]`, `removeLabels[]`

Gmail search query examples:

from:someone@example.com
subject:invoice
is:unread after:2024/01/01

📅 Google Calendar

Tool	Description	Key Parameters
`list_events`	List upcoming calendar events	`maxResults` (1–250, default 10), `timeMin?`, `timeMax?`
`create_event`	Create a new calendar event	`summary`, `start`, `end`, `location?`, `description?`, `attendees[]?`
`update_event`	Update an existing calendar event (partial patch)	`eventId`, any of: `summary`, `location`, `description`, `start`, `end`, `attendees[]`
`delete_event`	Delete a calendar event	`eventId`

All datetime values must be valid ISO 8601 strings (e.g., 2024-12-25T10:00:00Z).

Architecture

The server uses stateful Streamable HTTP sessions from the MCP SDK:

Each new MCP initialize request creates a fresh server + transport instance
Sessions are tracked in memory by mcp-session-id header
A single authenticated OAuth2 client is shared across Gmail and Calendar API calls within a session
Input validation is handled via Zod schemas on all tool inputs

Client → POST /mcp (initialize) → creates session
Client → POST /mcp (tool call, mcp-session-id: <id>) → reuses session

Testing

npm test                              # Run vitest unit tests
npx @anthropic-ai/mcp-inspector      # Interactive MCP tool testing UI
npm run test:smoke                    # Smoke test against running server

Connect MCP Inspector to http://localhost:8080/mcp to test tools interactively.

Deployment

MCPize (recommended)

mcpize deploy

Configured via mcpize.yaml:

Runtime: TypeScript
Build: npm ci && npm run build
Start: node dist/index.js (HTTP transport on $PORT)

Docker

docker build -t mcp-gsuite .
docker run -p 8080:8080 \
  -e GOOGLE_CLIENT_ID=... \
  -e GOOGLE_CLIENT_SECRET=... \
  -e GOOGLE_REFRESH_TOKEN=... \
  mcp-gsuite

Google Cloud Run

The server handles SIGTERM gracefully for zero-downtime Cloud Run deploys.

Tech Stack

Package	Version	Purpose
`@modelcontextprotocol/sdk`	^1.23.0	MCP server + Streamable HTTP transport
`googleapis`	^134.0.0	Gmail & Calendar API client
`express`	^5.1.0	HTTP server framework
`zod`	^4.0.0	Runtime input validation
`dotenv`	^16.4.5	Environment variable loading
`chalk`	^5.4.1	Colored terminal output
`tsx`	^4.19.4	TypeScript dev runner (hot reload)

Node.js requirement: >=20.0.0

License

MIT