🔧 Google Workspace MCP Server

A complete Model Context Protocol (MCP) server in Python that integrates Gmail and Google Docs into any MCP-compatible AI host (Claude Desktop, Cursor, etc.).

✨ Features

Gmail Tools (10)

Google Docs Tools (8)

Resources (7)

Prompt Templates (6)

Related MCP server: fastmcp-gsuite

🚀 Setup Guide

Step 1 — Create a Google Cloud Project

1. Go to Google Cloud Console

2. Click Select a project → New Project

3. Give it a name (e.g. MCP Workspace) and click Create

Step 2 — Enable Required APIs

In the Cloud Console, go to APIs & Services → Library and enable:

• ✅ Gmail API

• ✅ Google Docs API

• ✅ Google Drive API

Step 3 — Create OAuth 2.0 Credentials

1. Go to APIs & Services → Credentials

2. Click Create Credentials → OAuth 2.0 Client ID

3. If prompted, configure the OAuth consent screen:

   • User Type: External (or Internal for Workspace orgs)

   • Add your email as a test user

   • Add these scopes:

     • https://www.googleapis.com/auth/gmail.modify

     • https://www.googleapis.com/auth/gmail.compose

     • https://www.googleapis.com/auth/gmail.send

     • https://www.googleapis.com/auth/documents

     • https://www.googleapis.com/auth/drive

4. Application type: Desktop app

5. Click Create → Download JSON

6. Rename the downloaded file to credentials.json and place it in the MCP-SERVER directory

Step 4 — Install Dependencies

cd "C:\Users\Lavanya gupta\OneDrive\Documents\Ghratika\MCP-SERVER"
pip install -r requirements.txt

Or using a virtual environment (recommended):

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Step 5 — Configure Environment Variables

Copy the example .env file and fill it in:

copy .env.example .env

The defaults work out of the box if credentials.json is in the project root.

Step 6 — Run the First-Time Auth Flow

python auth/google_auth.py

This will:

1. Open your browser to the Google OAuth consent screen

2. Ask you to log in and grant permissions

3. Save a token.json file for future runs (no browser needed after this)

Step 7 — Test with MCP Inspector

mcp dev server.py

This opens an interactive web UI where you can:

• Browse all 18 tools, 7 resources, and 6 prompts

• Call tools and see responses in real-time

• Test authentication before connecting to Claude Desktop

🖥️ Claude Desktop Integration

1. Open Claude Desktop's config file:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Merge in the contents of claude_desktop_config.json from this project:

{
  "mcpServers": {
    "google-workspace": {
      "command": "python",
      "args": [
        "C:/Users/Lavanya gupta/OneDrive/Documents/Ghratika/MCP-SERVER/server.py"
      ],
      "env": {
        "GOOGLE_CREDENTIALS_PATH": "C:/Users/Lavanya gupta/OneDrive/Documents/Ghratika/MCP-SERVER/credentials.json",
        "GOOGLE_TOKEN_PATH": "C:/Users/Lavanya gupta/OneDrive/Documents/Ghratika/MCP-SERVER/token.json",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

3. Restart Claude Desktop — the Google Workspace tools will appear in the tools list.

Tip: If using a virtual environment, replace "python" with the full path to your venv Python: "C:/Users/Lavanya gupta/OneDrive/Documents/Ghratika/MCP-SERVER/.venv/Scripts/python.exe"

🌐 SSE (Remote HTTP) Mode

To run the server as an HTTP endpoint (e.g. for Cursor or remote clients):

python server.py --sse --port 8000

The server will be available at http://localhost:8000/sse.

📁 Project Structure

MCP-SERVER/
├── server.py                  ← Main entrypoint
├── credentials.json           ← Your OAuth2 client credentials (DO NOT COMMIT)
├── token.json                 ← Auto-generated after first login (DO NOT COMMIT)
├── .env                       ← Your environment variables (DO NOT COMMIT)
├── .env.example               ← Environment variable template
├── requirements.txt           ← Python dependencies
├── claude_desktop_config.json ← Ready-to-paste Claude Desktop config
├── auth/
│   └── google_auth.py         ← OAuth2 lifecycle manager
├── tools/
│   ├── gmail_tools.py         ← Gmail MCP tools
│   └── docs_tools.py          ← Google Docs MCP tools
├── resources/
│   ├── gmail_resources.py     ← Gmail MCP resources
│   └── docs_resources.py      ← Google Docs MCP resources
├── prompts/
│   └── google_prompts.py      ← MCP prompt templates
└── utils/
    ├── html_to_text.py        ← HTML → Markdown converter
    └── docs_parser.py         ← Google Docs JSON → Markdown parser

🔒 Security Notes

⚠️ Never commit these files to version control:

• credentials.json — your OAuth2 client secret

• token.json — your personal access token

• .env — your environment configuration

Add them to .gitignore:

credentials.json
token.json
.env

🔧 Troubleshooting

"credentials.json not found"

Download it from Google Cloud Console → APIs & Services → Credentials.

"Access blocked: This app's request is invalid"

Make sure the OAuth consent screen is configured and your email is added as a test user.

"Token has been expired or revoked"

Delete token.json and run python auth/google_auth.py again.

"ModuleNotFoundError: No module named 'mcp'"

Install dependencies: pip install -r requirements.txt

Tools not appearing in Claude Desktop

• Verify the path in claude_desktop_config.json uses forward slashes

• Check Claude Desktop logs at %APPDATA%\Claude\logs\

• Make sure Python is in your PATH

📖 Example Workflows

Summarise unread emails

"Check my unread emails and give me a daily digest" → Uses search_emails + daily_digest prompt

Draft and send a reply

"Reply to the latest email from john@example.com — say I'll be there" → Uses search_emails + get_email + send_email

Create a document from an email

"Turn this email thread into a Google Doc summary" → Uses get_email + create_document

Find and review a document

"Find my Q4 report document and review its structure" → Uses search_documents + get_document + review_document prompt