Google Workspace CRM MCP Server

A Python MCP (Model Context Protocol) server that acts as a lightweight CRM by integrating Google Sheets (contact management & generic spreadsheet ops), Gmail (email communication), and Google Docs (document creation). Designed for hosting on Replit with Streamable HTTP transport, compatible with both Claude and ChatGPT as MCP clients.

Features

• 30 MCP tools for full CRM + workspace workflow
• Google Sheets: CRM contacts + generic read/write/append on any range, tab management, and new spreadsheet creation
• Gmail integration via OAuth2 for sending, searching, reading emails, replying, and drafting (with SMTP and domain-wide delegation fallbacks)
• Google Docs: Create new documents, append text, read document content
• Agent Cache: Thread-safe in-memory cache with TTL expiration, LRU eviction, namespace support, and bulk operations for fast batch processing
• OAuth2 MCP endpoint protection: Secure the /mcp endpoint with Client Credentials or Authorization Code + PKCE flow — compatible with Claude's Advanced Settings
• Settings dashboard: Web-based UI for credential management, OAuth2 authorization, Google Sheets selection, and comprehensive testing
• Streamable HTTP transport for remote hosting on Replit
• Full audit logging: Every tool call is tracked through 5 stages (received, API call, Google validated, result delivered, delivery confirmed)
• Comprehensive test suite: One-click tests for Service Account, MCP Tools, Gmail Send & Reply, Cache Pipeline, and CRM Contact Management — each writes results to a dedicated Google Sheet tab
• Rate limiting & caching to stay within Google API quotas
• PostgreSQL-backed credentials: All service account keys, OAuth tokens, and settings stored securely in the database — never in code or files

MCP Tools (30 total)

CRM Contact Management (8 tools)

Google Sheets Operations (7 tools)

Google Workspace File Creation (4 tools)

Email Communication (7 tools)

Agent Cache (5 tools)

System & Audit (4 tools)

OAuth2 MCP Endpoint Security

The /mcp endpoint can be protected with OAuth2 authentication, preventing unauthorized access.

How It Works

When MCP_CLIENT_ID and MCP_CLIENT_SECRET are configured as secrets:

1. Discovery: Clients query /.well-known/oauth-authorization-server for metadata
2. Authorization: Clients redirect to /authorize with PKCE challenge
3. Token Exchange: Clients exchange the authorization code at /token for a Bearer token
4. Authenticated Access: All /mcp requests require Authorization: Bearer <token>

Without these secrets, the endpoint remains open (backward-compatible).

Supported Flows

• Authorization Code + PKCE — Used by Claude, ChatGPT, and browser-based clients
• Client Credentials — Used by server-to-server integrations

Security Features

• Credentials are only viewable/generatable in the development environment
• The live/deployed app hides Client IDs and blocks credential generation
• Tokens expire after 1 hour
• Authorization codes expire after 5 minutes and are single-use
• PKCE (S256) verification prevents code interception attacks
• Constant-time comparison (HMAC) prevents timing attacks

Test Endpoints

The Settings UI provides one-click test buttons for all major services:

Audit Logging System

Every tool call is tracked through a 5-stage lifecycle:

1. REQUEST_RECEIVED   → Incoming tool invocation from the chat agent
2. API_CALL           → Each Google API / SMTP call made by the server
3. GOOGLE_VALIDATED   → Confirmation the action landed on the Google side
4. RESULT_DELIVERED   → Response payload returned to the chat agent
5. DELIVERY_CONFIRMED → (Optional) Chat agent confirmed receipt

Every tool response includes an _audit field with the request_id:

{
  "contact": { ... },
  "message": "Contact added at row 5.",
  "_audit": { "request_id": "a1b2c3d4e5f6..." }
}

Agent Cache System

The in-memory agent cache enables fast batch processing workflows:

• TTL Expiration: Default 30-minute TTL, configurable per entry
• LRU Eviction: Automatic eviction when cache exceeds 10,000 entries
• Namespace Support: Organize entries by namespace (e.g., contacts, emails)
• Bulk Operations: List and delete entries by namespace
• Statistics: Track hits, misses, and hit rate
• Thread-Safe: Safe for concurrent access across MCP sessions
• Global Singleton: Shared across all tool calls for cross-request persistence

Google Sheet Schema

Create a Google Sheet and format the first row as headers:

Valid status values: lead, prospect, customer, churned

Important: Share the Google Sheet with your service account email (shown in the Settings UI after uploading the service account JSON). Give it Editor access.

Setup Instructions

1. Google Cloud Configuration

1. Go to Google Cloud Console
2. Select the project associated with your service account
3. Enable the following APIs:
   • Google Sheets API
   • Google Drive API
   • Gmail API
   • Google Docs API
4. Download the service account JSON key (or copy the existing one)

2. Settings Dashboard (Recommended)

The easiest way to configure everything is through the Settings UI at the root path (/):

1. Upload Service Account: Upload your Google Cloud service account JSON
2. Select CRM Sheet: Browse and select a Google Sheet for CRM data
3. Configure Gmail OAuth: Upload OAuth client credentials and authorize Gmail access
4. Enable MCP Auth: Generate and configure OAuth2 credentials for endpoint protection

3. Gmail Auth — Choose Your Path

Path C — OAuth2 (Recommended):

1. Create OAuth2 credentials in Google Cloud Console (Web Application type)
2. Upload the Client ID and Secret in the Settings UI
3. Click "Authorize Gmail" and complete the browser OAuth flow
4. Tokens are stored securely in PostgreSQL and refresh automatically

Path A — Google Workspace Domain-Wide Delegation: If your Gmail is on a Workspace domain (e.g., user@yourdomain.com):

1. Go to Google Workspace Admin Console → Security → API Controls → Domain-wide Delegation
2. Add the service account client ID with Gmail scopes
3. Set DELEGATED_USER_EMAIL=user@yourdomain.com

Path B — SMTP Fallback: If you use a personal @gmail.com account:

1. Enable 2-Step Verification on your Google Account
2. Generate an App Password at https://myaccount.google.com/apppasswords
3. Set USE_SMTP_FALLBACK=true, GMAIL_ADDRESS=your@gmail.com, GMAIL_APP_PASSWORD=xxxx xxxx xxxx xxxx

4. MCP Endpoint Security (Recommended)

To protect the /mcp endpoint with OAuth2:

1. In the Settings UI (development environment), click "Generate Credentials" in the MCP Authentication card
2. Copy the generated MCP_CLIENT_ID and MCP_CLIENT_SECRET
3. Add them as Replit Secrets (Tools → Secrets)
4. Restart the server
5. In Claude's MCP connector Advanced Settings, enter the same Client ID and Client Secret

5. Replit Secrets

Add these as Replit Secrets (Tools → Secrets):

All other credentials (service account, OAuth tokens, spreadsheet selection) are managed through the Settings UI and stored in PostgreSQL.

6. Deploy on Replit

1. Fork or import this repository into Replit
2. Configure credentials via the Settings UI
3. Click Run — the server starts on port 5000
4. On startup, connectivity checks run automatically and log results
5. Your MCP endpoint URL will be shown on the Settings dashboard

Connecting to MCP Clients

Claude (Web / Desktop)

1. Go to Claude Settings → MCP Servers → Add
2. Enter your MCP endpoint URL: https://your-app.replit.app/mcp
3. In Advanced Settings, enter your MCP_CLIENT_ID and MCP_CLIENT_SECRET
4. Claude will auto-discover the 30 tools

Claude Desktop (Config File)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "google-workspace-crm": {
      "url": "https://your-app.replit.app/mcp"
    }
  }
}

Claude Code (CLI)

claude mcp add google-workspace-crm --transport http https://your-app.replit.app/mcp

ChatGPT

ChatGPT supports MCP servers via its plugin/actions system:

1. In your Custom GPT configuration, go to Actions
2. Import the MCP endpoint URL
3. ChatGPT will auto-discover the available tools via Streamable HTTP

Any MCP-Compatible Client

Endpoint: https://your-app.replit.app/mcp
Transport: Streamable HTTP
OAuth2 Metadata: https://your-app.replit.app/.well-known/oauth-authorization-server
Token Endpoint: https://your-app.replit.app/token

Project Structure

├── main.py                     # MCP server entry point (30 tools, OAuth2 auth, startup checks)
├── config.py                   # Environment config loader
├── requirements.txt            # Python dependencies
├── tools/
│   ├── sheets.py               # CRM tools (8) + generic sheet tools (7)
│   ├── gmail.py                # Gmail tools (5) + workflow tools (2)
│   ├── workspace.py            # Spreadsheet/Doc creation (4) + audit tools (3)
│   └── cache.py                # Agent cache tools (5)
├── services/
│   ├── google_auth.py          # Service account credential loading
│   ├── sheets_client.py        # gspread client with caching & rate limiting
│   ├── gmail_client.py         # Gmail API / SMTP client wrapper
│   ├── docs_client.py          # Google Docs + Drive API client
│   ├── cache.py                # Thread-safe agent cache (TTL, LRU, namespaces)
│   ├── mcp_auth.py             # OAuth2 auth for MCP endpoint (PKCE, tokens)
│   ├── audit_logger.py         # 5-stage audit log with ring buffer
│   └── health_check.py         # Connectivity testing for all Google services
├── web/
│   ├── routes.py               # Settings UI routes & test endpoints
│   ├── settings_store.py       # PostgreSQL-backed settings storage
│   ├── oauth.py                # Gmail OAuth2 flow handler
│   ├── sheets_browser.py       # Google Sheets browser for selection UI
│   └── templates/
│       └── settings.html       # Settings dashboard UI
└── models/
    └── contact.py              # Pydantic models

Rate Limits & Caching

• Google Sheets API: 60 requests/minute (gspread default) — the server enforces this with a token-bucket rate limiter at 55/min
• Sheet data is cached for 30 seconds to minimize API calls on repeated list/search operations
• Agent cache provides 30-minute TTL with 10,000 entry max and LRU eviction
• Audit log keeps last 500 entries in an in-memory ring buffer
• All timestamps are ISO 8601 UTC

License

MIT