Skip to main content
Glama
khokan

mcp-gsuite

by khokan
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Remote

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

Related MCP server: Google Calendar MCP Server

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

This server cannot be installed

F
license - not found
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/khokan/mcp-gsuite'

If you have feedback or need assistance with the MCP directory API, please join our Discord server