Google Workspace MCP Server

A Model Context Protocol (MCP) server that enables AI agents to interact with Google Workspace — specifically Gmail (draft emails) and Google Docs (append content).

Primary Use Case: Review Analysis Pipeline

An AI agent collects product reviews, normalizes ratings to a 5-point scale, performs sentiment analysis, and uses this MCP server to:

• Append the full analysis report to a Google Doc

• Draft a summary notification email via Gmail

Related MCP server: Gmail & Google Docs MCP Server

Quick Start

Prerequisites

• Node.js 18+ installed

• A Google Cloud project with Gmail API and Google Docs API enabled

• OAuth 2.0 Client ID credentials (Desktop application type)

1. Clone & Install

git clone https://github.com/<your-username>/google-workspace-mcp.git
cd google-workspace-mcp
npm install

2. Configure Environment

cp .env.example .env

Edit .env and add your Google OAuth credentials:

GOOGLE_CLIENT_ID="your-client-id-here"
GOOGLE_CLIENT_SECRET="your-client-secret-here"

3. Build

npm run build

4. Run Locally (Stdio — for local MCP clients)

npm start

On first run, the server will print an authorization URL. Open it in your browser, sign in with your Google account, and grant the requested permissions. A token.json file will be created automatically.

5. Run as HTTP Server (for Railway / remote deployment)

npm run start:http

This starts an Express server with Streamable HTTP transport on port 3000.

Connect to an MCP Client

Claude Desktop (Local — Stdio)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["<path-to-project>/build/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Claude Desktop (Remote — Railway)

{
  "mcpServers": {
    "google-workspace": {
      "url": "https://<your-app>.up.railway.app/mcp",
      "transport": "streamable-http"
    }
  }
}

Available Tools

Deploy to Railway

1. Push this repo to GitHub

2. Go to railway.app → New Project → Deploy from GitHub Repo

3. Set environment variables in Railway dashboard:

   • GOOGLE_CLIENT_ID

   • GOOGLE_CLIENT_SECRET

   • GOOGLE_OAUTH_TOKEN (paste contents of your local token.json)

4. Railway will auto-build and deploy using railway.json config

See deploymentplan.md for detailed deployment instructions.

Google Cloud Setup

1. Go to Google Cloud Console

2. Create a new project (or select existing)

3. Enable Gmail API and Google Docs API

4. Go to Credentials → Create Credentials → OAuth Client ID

5. Application type: Desktop application

6. Download the credentials and copy Client ID and Client Secret to .env

7. Configure the OAuth consent screen (add test users if in testing mode)

Project Structure

google-workspace-mcp/
├── src/
│   ├── index.ts       # MCP server entry point (Stdio transport — local)
│   ├── server.ts      # MCP server entry point (HTTP transport — Railway)
│   ├── auth.ts        # OAuth 2.0 authentication & token caching
│   ├── gmail.ts       # Gmail draft creation
│   └── docs.ts        # Google Docs content appending
├── .env.example       # Environment variable template
├── railway.json       # Railway deployment configuration
├── package.json       # Dependencies & scripts
├── tsconfig.json      # TypeScript configuration
└── README.md          # This file

Security Notes

• Tokens are local: token.json is stored locally and never committed

• Drafts only: Emails are saved as drafts — the user must manually send

• Scoped access: Only requests gmail.compose and documents scopes

• No data sent to AI: All auth is handled server-side

License

ISC