Google Cloud MCP - Google Workspace MCP Server (gg-mcp)

A Model Context Protocol (MCP) server that connects AI agents to Google Workspace: Gmail, Calendar, Drive, Docs, Sheets, and Slides. Built with FastMCP.

# Install and run — that's it
uvx gg-mcp

� Table of Contents

1. Quick Start (5 minutes)
2. Available Tools
3. Installation Options
4. Environment Variables
5. Troubleshooting
6. Documentation
7. Development

🚀 Quick Start (5 minutes)

Step 1: Get Google OAuth Credentials

1. Go to Google Cloud Console
2. Create a project and enable OAuth consent screen (External type)
3. Add required scopes (Gmail, Drive, Calendar, Docs, Sheets, Slides)
4. Create OAuth 2.0 Desktop app credentials
5. Copy Client ID and Client Secret

📖 Detailed guide →

Step 2: Install & Run

export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="your-client-secret"
uvx gg-mcp

You'll see:

============================================================
🔐 GOOGLE ACCOUNT AUTHENTICATION
📱 Open your browser: http://localhost:3838
============================================================

Open http://localhost:3838 → "Authorize with Google" → Grant permissions ✅

Step 3: Configure MCP Client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "gg-mcp": {
      "command": "uvx",
      "args": ["gg-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Restart Claude Desktop and the tools are ready to use! 🎉

📖 25+ client configs →

📋 Available Tools (30+)

Account

• get_account_info - Get the email of the authenticated Google account

Gmail

• send_email - Send an email (to, subject, body)
• create_gmail_label - Create a new Gmail label
• list_gmail_labels - List all user-created labels

Google Calendar

• list_calendar_events - List upcoming events (max_results, days_back)
• create_calendar_event - Create an event (summary, start_time, end_time)

Google Drive

• list_drive_folders - List all folders in Google Drive (root or specific parent)
• search_drive - Search files by query string

Google Docs

• create_document - Create a new document with optional text
• get_document - Get the full text content of a document
• append_to_document - Append text to document end
• search_documents - Search for documents in Drive
• export_document - Export document (text, html, pdf, docx)

Google Sheets

• create_spreadsheet - Create a new spreadsheet
• read_spreadsheet - Read data from a range
• update_spreadsheet - Update cells with JSON 2D array
• append_to_spreadsheet - Append rows to spreadsheet
• search_spreadsheets - Search for spreadsheets in Drive
• get_spreadsheet_info - Get metadata and dimensions
• clear_spreadsheet_range - Clear all values in a range
• batch_update_spreadsheet - Batch update multiple ranges
• add_sheet - Add a new sheet/tab
• export_spreadsheet - Export (csv, xlsx, pdf, tsv)

Google Slides

• create_presentation - Create a new presentation
• get_presentation - Get slide metadata and content
• add_slide - Add a new slide with layout selection
• add_text_to_slide - Add a text box to slide
• search_presentations - Search for presentations
• delete_slide - Delete a slide by index
• export_presentation - Export (pdf, pptx, txt)

🚀 Quick Start (5 minutes)

Step 1: Get Google OAuth Credentials

1. Go to Google Cloud Console
2. Create a project and enable OAuth consent screen (External type)
3. Add required scopes (Gmail, Drive, Calendar, Docs, Sheets, Slides)
4. Create OAuth 2.0 Desktop app credentials
5. Copy Client ID and Client Secret

📖 Detailed guide →

Step 2: Install & Run

export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="your-client-secret"
uvx gg-mcp

You'll see:

============================================================
🔐 GOOGLE ACCOUNT AUTHENTICATION
📱 Open your browser: http://localhost:3838
============================================================

Open http://localhost:3838 → "Authorize with Google" → Grant permissions ✅

Step 3: Configure MCP Client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "gg-mcp": {
      "command": "uvx",
      "args": ["gg-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

📖 25+ client configs →

📦 Installation Options

Option A: PyPI (Recommended)

pip install gg-mcp
export GOOGLE_CLIENT_ID="..."
export GOOGLE_CLIENT_SECRET="..."
gg-mcp

Option B: From Source

git clone https://github.com/tannht/google-cloud-mcp.git
cd google-cloud-mcp
uv sync
export GOOGLE_CLIENT_ID="..."
export GOOGLE_CLIENT_SECRET="..."
uv run main.py

Option C: Docker

git clone https://github.com/tannht/google-cloud-mcp.git
cd google-cloud-mcp
docker-compose up -d --build

🔑 Environment Variables

| Variable | Required | Default | Purpose | |----------|----------|---------|---------| | GOOGLE_CLIENT_ID | Yes | — | OAuth 2.0 Client ID | | GOOGLE_CLIENT_SECRET | Yes | — | OAuth 2.0 Client Secret | | GOOGLE_TOKEN_PATH | No | .token.json | Token file path | | GOOGLE_TOKEN_JSON | No | — | Token as JSON string | | AUTH_PORT | No | 3838 | Auth portal port |

❓ Troubleshooting

| Problem | Solution | |---------|----------| | 403: access_denied | Add your email to Test users in OAuth consent screen | | 401: Invalid credentials | Verify GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET | | Token expired | Delete .token.json and re-authenticate | | Can't access http://localhost:3838 | Port 3838 in use. Try AUTH_PORT=8080 | | 403: API not enabled | Enable APIs in Google Cloud Console |

📖 Full troubleshooting →

📚 Documentation

• GUIDE.md - Complete user & developer guide
• MCP_CLIENTS.md - 25+ MCP client configurations

🛠️ Development

git clone https://github.com/tannht/google-cloud-mcp.git
cd google-cloud-mcp
uv sync --group dev
uv run pytest -v  # Run tests

📖 Dev setup →

📄 License

MIT

👥 Contributors

• Hoang Tan (Owner)
• PubPug Assistant (Primary Developer)