mcp-gsuite

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

1. A Google Cloud project with the following APIs enabled:
   • Gmail API
   • Google Calendar API
2. OAuth 2.0 Web Application credentials — download as credentials.json from Google Cloud Console
3. 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