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)