gg-mcp

README.md

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

[![PyPI](https://img.shields.io/pypi/v/gg-mcp.svg)](https://pypi.org/project/gg-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![Docker Support](https://img.shields.io/badge/Docker-Supported-blue.svg?logo=docker)](https://www.docker.com/)

A Model Context Protocol (MCP) server that connects AI agents to Google Workspace: **Gmail**, **Calendar**, **Drive**, **Docs**, **Sheets**, and **Slides**. Built with [FastMCP](https://github.com/jlowin/fastmcp).

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

---

## � Table of Contents
1. [Quick Start (5 minutes)](#-quick-start-5-minutes)
2. [Available Tools](#-available-tools-30)
3. [Installation Options](#-installation-options)
4. [Environment Variables](#-environment-variables)
5. [Troubleshooting](#-troubleshooting)
6. [Documentation](#-documentation)
7. [Development](#-development)

---

## 🚀 Quick Start (5 minutes)

### Step 1: Get Google OAuth Credentials
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
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 →](GUIDE.md#step-1-get-your-google-oauth-credentials)**

### Step 2: Install & Run
```bash
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`):
```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 →](MCP_CLIENTS.md)**

---

## 📋 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](https://console.cloud.google.com/)
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 →](GUIDE.md#step-1-get-your-google-oauth-credentials)**

### Step 2: Install & Run
```bash
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`):
```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 →](MCP_CLIENTS.md)**

---

## 📦 Installation Options

**Option A: PyPI (Recommended)**
```bash
pip install gg-mcp
export GOOGLE_CLIENT_ID="..."
export GOOGLE_CLIENT_SECRET="..."
gg-mcp
```

**Option B: From Source**
```bash
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**
```bash
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](https://console.cloud.google.com/apis/library) |

📖 **[Full troubleshooting →](GUIDE.md#troubleshooting)**

---

## 📚 Documentation

- **[GUIDE.md](GUIDE.md)** - Complete user & developer guide
- **[MCP_CLIENTS.md](MCP_CLIENTS.md)** - 25+ MCP client configurations

---

## 🛠️ Development

```bash
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 →](GUIDE.md#for-developers---setup)**

---

## 📄 License

MIT

## 👥 Contributors

- **Hoang Tan** (Owner)
- **PubPug Assistant** (Primary Developer)

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored 2026-06-23 01:50 across 30 tools

Disambiguation5/5

Each tool targets a specific Google service and action (e.g., create, read, update, search, export), with clear names that distinguish between resources like documents, spreadsheets, slides, Gmail, Calendar, and Drive. There is no ambiguity between tools.

Naming Consistency5/5

All tools use consistent snake_case naming with a verb-first pattern (e.g., create_document, list_calendar_events, get_spreadsheet_info). The naming convention is uniform across the entire set, making it predictable for an agent.

Tool Count5/5

With 30 tools covering multiple Google services (Docs, Sheets, Slides, Gmail, Calendar, Drive, account info), the count is appropriate for a comprehensive Google Workspace integration. Each tool serves a distinct purpose without redundancy.

Completeness3/5

The tool set covers core create, read, search, and export operations for most resources but lacks update and delete for documents, presentations, and calendar events. This is a notable gap for full CRUD workflows, though the set is still functional for many use cases.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers