Your AI can reason. But can it check your calendar?

The complete Google Workspace bridge for AI agents — 47 operations, one URL.

See It In Action · Quick Start · Documentation

---

The Problem

AI agents can write code, analyze documents, and plan complex projects. But ask one to send an email, schedule a meeting, or update a spreadsheet — and it hits a wall.

• Your agent drafts a project plan but can't put it in Google Docs
• It analyzes data but can't write results back to Sheets
• It schedules tasks but can't check anyone's calendar
• It composes emails but can't actually send them

Google Workspace is where work lives. If your AI can't touch it, your AI can't finish the job.

You don't need a smarter model. You need a model that can reach the tools people actually use.

---

The Insight

AI agents don't lack intelligence.

They lack hands.

The Model Context Protocol gives AI agents a standardized way to interact with external tools. But most MCP servers require local installation, credential management, and manual path configuration before a single API call can be made.

v4 changes this entirely. Deploy once to Cloudflare Workers, get a URL. That URL is your MCP server — available everywhere, always-on, zero local setup required.

One URL. Six services. Full autonomy.

---

What's New in v4.0.0

This is a breaking change release. v4 introduces a 2-tool SDK architecture and Cloudflare Workers deployment. The legacy 6-tool stdio server is preserved for local use.

Zero-Install Remote Deployment

Deploy the server to Cloudflare Workers and connect any MCP client with a single URL — no Node.js, no Docker, no path configuration. Just:

https://your-worker.workers.dev/mcp

Inspired by Cloudflare's approach to remote MCP servers — thanks to @mattzcarey for surfacing this.

2-Tool SDK Architecture

Tool	Purpose
search	Query Google Workspace via natural language SDK spec
execute	Run sandboxed JavaScript with full googleapis SDK access

88% fewer tools in your agent's context window. The SDK handles the rest dynamically.

KV-Backed Token Storage

OAuth tokens stored in Cloudflare KV — encrypted, persistent, no local credential files needed.

---

Introducing gdrive MCP Server

A production-ready MCP server that gives AI agents complete, secure access to Google Workspace.

Service	Operations	Highlights
Drive	7	Search, enhanced search, read, create, update, batch operations
Sheets	12	Read/write cells, formulas, formatting, conditional formatting, freeze, column width
Gmail	10	List, search, read, draft, send emails, send drafts, manage labels
Calendar	9	Full CRUD, natural language quickAdd, free/busy checks
Docs	5	Create, insert text, replace, rich text styling, insert tables
Forms	4	Create forms, add questions, read responses
	47 total

---

See It In Action

Send an email and schedule a follow-up — in two calls

// 1. Send the email
{
  "tool": "gmail",
  "args": {
    "operation": "sendMessage",
    "to": "team@company.com",
    "subject": "Q1 Report Ready",
    "body": "The Q1 report is complete. Link: https://docs.google.com/..."
  }
}

// 2. Schedule the review meeting
{
  "tool": "calendar",
  "args": {
    "operation": "quickAdd",
    "text": "Q1 Report Review with team tomorrow at 2pm",
    "calendarId": "primary"
  }
}

Build a formatted spreadsheet from scratch

// 1. Create the spreadsheet
{ "tool": "drive", "args": { "operation": "createFile", "name": "Sales Dashboard", "mimeType": "application/vnd.google-apps.spreadsheet" } }

// 2. Add data
{ "tool": "sheets", "args": { "operation": "updateCells", "spreadsheetId": "...", "range": "Sheet1!A1:D4",
    "values": [["Region", "Q1", "Q2", "Total"], ["North", 50000, 62000, ""], ["South", 43000, 51000, ""], ["West", 67000, 71000, ""]] } }

// 3. Add formulas
{ "tool": "sheets", "args": { "operation": "updateFormula", "spreadsheetId": "...", "range": "D2:D4", "formula": "=B2+C2" } }

// 4. Format the header row
{ "tool": "sheets", "args": { "operation": "formatCells", "spreadsheetId": "...", "sheetId": 0,
    "range": { "startRowIndex": 0, "endRowIndex": 1 },
    "format": { "textFormat": { "bold": true }, "backgroundColor": { "red": 0.2, "green": 0.4, "blue": 0.8 } } } }

// 5. Freeze the header
{ "tool": "sheets", "args": { "operation": "freezeRowsColumns", "spreadsheetId": "...", "sheetId": 0, "frozenRowCount": 1 } }

Check availability and book a meeting

// 1. Check if everyone is free
{ "tool": "calendar", "args": { "operation": "checkFreeBusy",
    "timeMin": "2025-03-15T14:00:00Z", "timeMax": "2025-03-15T15:00:00Z",
    "items": ["alice@company.com", "bob@company.com"] } }

// 2. Book it
{ "tool": "calendar", "args": { "operation": "createEvent", "calendarId": "primary",
    "summary": "Design Review", "start": "2025-03-15T14:00:00Z", "end": "2025-03-15T15:00:00Z",
    "attendees": ["alice@company.com", "bob@company.com"],
    "description": "Reviewing the new dashboard designs" } }

---

Quick Start

Option 1: Remote (Cloudflare Workers) — Recommended

Deploy once to Cloudflare's edge — connect from anywhere via a permanent URL. After the initial setup, no local process to manage.

Prerequisites:

• Cloudflare account (free tier works)
• Node.js 18+ (needed for the one-time local auth step)
• Wrangler CLI: npm install -g wrangler or use npx wrangler
• Google Cloud project with OAuth credentials
• just — brew install just (macOS) · winget install just (Windows) · cargo install just (cross-platform)

Guided setup: Run just install to have Claude walk you through every step interactively — GCP project creation, API enablement, OAuth credentials, KV setup, and deploy. Or follow the steps below manually.

1. Clone and install

git clone https://github.com/AojdevStudio/gdrive.git
cd gdrive
npm install && npm run build

2. Authenticate with Cloudflare

npx wrangler login

3. Create KV namespace for token storage

npx wrangler kv:namespace create GDRIVE_KV --preview false
# Copy the `id` from the output, update [[kv_namespaces]] id in wrangler.toml

4. Complete Google OAuth locally

# Generate encryption key
echo "GDRIVE_TOKEN_ENCRYPTION_KEY=$(openssl rand -base64 32)" > .env

# Place your gcp-oauth.keys.json in credentials/
mkdir -p credentials
cp /path/to/gcp-oauth.keys.json credentials/

# Run auth — opens browser, saves tokens to .tokens.json
node ./dist/index.js auth

Don't have Google Cloud credentials? Follow the Google Cloud setup guide — or run just install for a fully guided walkthrough.

5. Upload tokens and secrets to Cloudflare

# Upload OAuth tokens to KV
npx wrangler kv:key put --namespace-id=<KV_NAMESPACE_ID> \
  "gdrive:oauth:tokens" "$(cat .tokens.json)"

# Set OAuth client credentials as Wrangler secrets
npx wrangler secret put GDRIVE_CLIENT_ID
npx wrangler secret put GDRIVE_CLIENT_SECRET

6. Deploy

npx wrangler deploy
# Note the URL printed: https://your-worker.workers.dev

7. Connect to Claude

Claude Code CLI — User scope (available in every project, stored in ~/.claude/settings.json):

claude mcp add --scope user --transport http gdrive https://your-worker.workers.dev/mcp

Claude Code CLI — Project scope (this project only, can be committed to the repo):

claude mcp add --scope project --transport http gdrive https://your-worker.workers.dev/mcp

Why user scope? An MCP server that connects to your Google account belongs at the user level — not locked to one project. Use --scope project only when the server is project-specific (different Google account, different permissions).

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gdrive": {
      "url": "https://your-worker.workers.dev/mcp"
    }
  }
}

---

Option 2: Local (Node.js stdio)

For local development or when you prefer to keep everything on-machine.

Prerequisites

• Node.js 18+
• Google Cloud project with OAuth credentials

New to Google Cloud? Follow the detailed setup guide.

Install & Authenticate

git clone https://github.com/AojdevStudio/gdrive.git
cd gdrive
npm install && npm run build

# Copy your OAuth credentials
mkdir -p credentials
cp /path/to/gcp-oauth.keys.json credentials/

# Generate encryption key and authenticate
export GDRIVE_TOKEN_ENCRYPTION_KEY=$(openssl rand -base64 32)
node ./dist/index.js auth

Connect to Claude

Claude Code CLI — User scope (recommended — works across all your projects):

claude mcp add --scope user gdrive -- node /absolute/path/to/gdrive/dist/index.js

Claude Code CLI — Project scope:

claude mcp add --scope project gdrive -- node /absolute/path/to/gdrive/dist/index.js

Claude Desktop:

{
  "mcpServers": {
    "gdrive": {
      "command": "node",
      "args": ["/absolute/path/to/gdrive/dist/index.js"],
      "env": {
        "GDRIVE_TOKEN_ENCRYPTION_KEY": "your-key-here"
      }
    }
  }
}

---

Option 3: Docker (Self-Hosted Production)

For teams that need a persistent, shared instance with Redis caching.

# Authenticate on host first (opens browser)
./scripts/auth.sh

# Start with Redis caching
docker compose up -d --build

# Verify
docker compose ps

Claude Desktop with Docker:

{
  "mcpServers": {
    "gdrive": {
      "command": "docker",
      "args": ["exec", "-i", "gdrive-mcp-server", "node", "dist/index.js"]
    }
  }
}

---

How It Works

Operation-Based Tool Pattern

Instead of 47 separate tools competing for your agent's attention, the server exposes 6 tools with an operation parameter:

// One tool per service, operation parameter for routing
{
  name: "sheets",
  args: {
    operation: "formatCells",    // ← The operation discriminator
    spreadsheetId: "abc123",
    sheetId: 0,
    range: { startRowIndex: 0, endRowIndex: 1 },
    format: { textFormat: { bold: true } }
  }
}

This means 88% fewer tools in your agent's context window — faster tool selection, lower token cost, better results.

Security

• AES-256-GCM encryption for all stored tokens
• Automatic OAuth refresh — authenticate once, works forever
• Key rotation with V1-V4 versioned keys
• Redis caching with intelligent invalidation (optional, graceful fallback)
• Sandboxed execution via isolated-vm
• Comprehensive audit trail in structured logs

---

The Story

This project started because we kept hitting the same wall: AI agents that could think brilliantly but couldn't do anything in the real world.

Every time we wanted an agent to update a spreadsheet, check a calendar, or send an email, we had to leave the AI loop, do it manually, and come back. The agent was a great thinker trapped in a box.

MCP changed the game by giving agents a standard way to use tools. But the existing Google integrations were shallow — basic file read/write, no formatting, no email sending, no calendar management. We needed something that matched the depth of what people actually do in Google Workspace every day.

So we built it. Starting with Drive and Sheets, then Forms and Docs, then Gmail (with actual sending, not just drafts), and finally Calendar with full CRUD and natural language scheduling. Each release driven by the same question: "What does an agent need to actually finish this job without human intervention?"

v4 answers the next question: "What does a developer need to connect their agent in under 60 seconds?" One URL. That's the answer.

The best AI assistant isn't the smartest one. It's the one that can actually get things done.

---

Complete API Reference

All 47 Operations

Drive — 7 operations

Operation	Description
search	Search files with queries
enhancedSearch	Natural language search with intelligent filtering
read	Read file content (auto-converts Google formats)
createFile	Create new files
createFolder	Create new folders
updateFile	Update existing files
batchOperations	Bulk create/update/delete/move

Sheets — 12 operations

Operation	Description
listSheets	List all sheets in a spreadsheet
readSheet	Read data from a range
createSheet	Create a new sheet tab
renameSheet	Rename a sheet tab
deleteSheet	Delete a sheet tab
updateCells	Write values to cells
updateFormula	Write formulas with relative reference support
formatCells	Apply formatting (bold, colors, borders, number formats)
addConditionalFormat	Add conditional formatting rules
freezeRowsColumns	Freeze header rows/columns
setColumnWidth	Adjust column widths
appendRows	Append rows to end of data

Gmail — 10 operations

Operation	Description
listMessages	List messages with optional query
listThreads	List email threads
getMessage	Get full message content
getThread	Get full thread content
searchMessages	Advanced message search
createDraft	Create email draft
sendMessage	Send email (supports send-as aliases)
sendDraft	Send an existing draft
listLabels	List all Gmail labels
modifyLabels	Add/remove labels on messages

Calendar — 9 operations

Operation	Description
listCalendars	List available calendars
getCalendar	Get calendar details
listEvents	List events in a time range
getEvent	Get event details
createEvent	Create a new event with attendees
updateEvent	Modify an existing event
deleteEvent	Delete event with notification options
quickAdd	Natural language event creation
checkFreeBusy	Check availability for scheduling

Docs — 5 operations

Operation	Description
createDocument	Create a new document
insertText	Insert text at a position
replaceText	Find and replace text
applyTextStyle	Apply formatting (bold, italic, colors, fonts)
insertTable	Insert a table with custom dimensions

Forms — 4 operations

Operation	Description
createForm	Create a new form
readForm	Get form structure and details
addQuestion	Add questions (text, multiple choice, checkboxes, scales)
listResponses	Retrieve form responses

---

Roadmap

• Google Drive — file management and search
• Google Sheets — full spreadsheet control with formatting
• Google Forms — form creation and response management
• Google Docs — document creation and rich text editing
• Gmail — complete email management including send
• Calendar — full CRUD with natural language scheduling
• Cloudflare Workers — zero-install remote deployment
• Google Slides — presentation creation and editing
• Google Chat — workspace messaging integration
• Contacts — contact management and lookup
• Tasks — Google Tasks integration

Contributing

We welcome contributions! The codebase is TypeScript with a clean module structure:

src/modules/
  drive/     — 9 files
  sheets/    — 9 files
  gmail/     — 12 files
  calendar/  — 13 files
  docs/      — 2 files
  forms/     — 7 files

1. Fork and create a feature branch
2. Follow existing TypeScript/ESLint conventions
3. Add tests (Jest) and update docs
4. npm run lint && npm test && npm run build
5. Open a PR with a clear description

Contributing Guide · Development Setup

License

MIT — see LICENSE for details.

---

Your AI agent can now do everything you do in Google Workspace.

If this project helps your agents get work done, give it a star.