---
title: Google Workspace MCP Server
emoji: 📧
colorFrom: blue
colorTo: green
sdk: docker
app_file: app.py
pinned: false
---

# Google Workspace Model Context Protocol (MCP) Server

A reusable, production-ready **Model Context Protocol (MCP) Server** that bridges AI agents with Google Workspace services (Gmail & Google Docs). By exposing standardized productivity tools, this server allows any MCP-compatible AI agent (such as Claude Desktop, IDE assistants, or autonomous workflows) to securely compose emails and edit documents without requiring hardcoded Google API logic.

---

## Features & Capabilities

### 📧 Gmail Integration
* **`send_email`**: Send emails immediately with validation for `to`, `cc`, and `bcc` lists. Supports both plain text and HTML alternative body rendering.
* **`draft_email`**: Create drafts in your Gmail mailbox for subsequent manual review before sending.

### 📄 Google Docs Integration
* **`append_content`**: Append plain text or formatted notes to the end of any Google Document. Supports Heading styles (`HEADING_1`, `HEADING_2`, `HEADING_3`), bulleted lists, numbered lists, bold text, and italic text.

### 🔐 Secure & Transparent Authentication
* Implements Google OAuth 2.0 with PKCE for enhanced desktop security.
* Automatically checks token expiration and performs silent background refreshes using stored refresh tokens without interrupting AI agent execution.
* AI agents are strictly isolated from raw tokens or client secrets.

---

## Quickstart Guide

### 1. Requirements & Setup
Ensure you have Python 3.10+ installed. Create a virtual environment and install dependencies:

```bash
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .
```

### 2. Configure OAuth Client Secrets
1. Follow the step-by-step instructions in [docs/GCP_SETUP.md](file:///Users/vkg/Desktop/MCP%20Server/docs/GCP_SETUP.md) to enable Gmail and Docs APIs in Google Cloud Console.
2. Download your **Desktop App** OAuth client secrets JSON file.
3. Save the downloaded file to your project root or configure its path in your `.env` file:
   ```env
   GOOGLE_CLIENT_SECRETS_FILE=client_secret_YOUR_ID.json
   TOKEN_STORAGE_PATH=token.json
   LOG_LEVEL=INFO
   ```

### 3. Authorize Your Google Account
Before running the MCP server, perform a one-time interactive login to generate your `token.json`:

```bash
workspace-auth
```
*(This opens a browser window. Sign in with your Google account and grant permissions).*

---

## Connecting to AI Agents

### Option A: Claude Desktop Configuration
To connect this MCP server to Claude Desktop, add the following entry to your `claude_desktop_config.json` (located at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "google-workspace": {
      "command": "/Users/vkg/Desktop/MCP Server/.venv/bin/workspace-mcp",
      "args": ["--transport", "stdio"],
      "cwd": "/Users/vkg/Desktop/MCP Server",
      "env": {
        "GOOGLE_CLIENT_SECRETS_FILE": "/Users/vkg/Desktop/MCP Server/client_secret_YOUR_ID.json",
        "TOKEN_STORAGE_PATH": "/Users/vkg/Desktop/MCP Server/token.json"
      }
    }
  }
}
```

### Option B: Run via Server-Sent Events (SSE)
For network-based AI agents, launch the server in SSE mode:

```bash
workspace-mcp --transport sse --port 8000
```
Then connect your client to `http://localhost:8000/sse`.

---

## Documentation Suite
* **[Hugging Face Deployment Guide](file:///Users/vkg/Desktop/MCP%20Server/docs/HUGGINGFACE_DEPLOYMENT.md)**: Complete step-by-step tutorial for cloud container hosting on Hugging Face Spaces.
* **[GCP Setup Guide](file:///Users/vkg/Desktop/MCP%20Server/docs/GCP_SETUP.md)**: Detailed step-by-step tutorial on creating GCP projects and credentials.
* **[Configuration Guide](file:///Users/vkg/Desktop/MCP%20Server/docs/CONFIGURATION.md)**: Advanced environment variables, scopes, and multi-account readiness.
* **[Troubleshooting Guide](file:///Users/vkg/Desktop/MCP%20Server/docs/TROUBLESHOOTING.md)**: Solutions for common OAuth errors, token expiration, and permission denials.
* **[Problem Statement & Architecture](file:///Users/vkg/Desktop/MCP%20Server/ProblemStatement.md)**: Architectural specifications and tool schemas.