Google Workspace MCP Server

Google Workspace MCP

Python MCP server for reading Google Docs and Google Sheets with structured output and better image handling.

What It Does

• Reads Google Docs as structured JSON with paragraphs, tables, inline objects, positioned objects, and image metadata.
• Reads Google Sheets values, grid data, formulas, notes, hyperlinks, and chip runs.
• Preserves partial text styling in Sheets cells via text_runs and an annotated_text helper field for segments such as strikethrough and underline.
• Extracts over-grid sheet images from Drive export -> XLSX.
• Detects in-cell IMAGE("...") formulas separately from drawing exports.

Project Layout

google_workspace_mcp/
  cli.py        # command-line entrypoint
  client.py     # Google API auth + HTTP client
  common.py     # shared constants and parsing helpers
  docs.py       # Google Docs normalization helpers
  server.py     # FastMCP server instance
  sheets.py     # Google Sheets normalization helpers
  tools.py      # MCP tool definitions
mcp_google_workspace.py  # compatibility wrapper for local scripts/config
tests/

Authentication Options

Recommended for private files shared to your Google account: OAuth desktop client

Use a Google OAuth client ID for Desktop App if the files are private but shared to your personal Google account.

1. Enable:
   • Google Sheets API
   • Google Docs API
   • Google Drive API
2. Create an OAuth client ID with application type Desktop app.
3. Download the client secret JSON.
4. Set:

$env:GOOGLE_OAUTH_CLIENT_SECRETS_FILE="C:\path\to\oauth-client-secret.json"

5. Run the one-time browser login flow:

google-workspace-mcp auth

This stores a refreshable token by default at:

$HOME\.google-workspace-mcp\oauth-token.json

Use this to inspect the cached token scopes and see which scopes are still missing:

google-workspace-mcp auth status

If you need to overwrite the cached token with a specific client secret file and token path, you can also run:

google-workspace-mcp auth login --client-secrets C:\path\to\oauth-client-secret.json --token-file C:\path\to\oauth-token.json

Recommended: service account

Use a Google Cloud service account for the most reliable setup.

1. Enable:
   • Google Sheets API
   • Google Docs API
   • Google Drive API
2. Create a service account key.
3. Share the target Docs/Sheets files with the service account email.
4. Set:

$env:GOOGLE_SERVICE_ACCOUNT_FILE="C:\path\to\service-account.json"

Public Sheets only: API key

Suitable for public Google Sheets reads. Not recommended for Docs or Drive export.

$env:GOOGLE_API_KEY="your_api_key"

Existing bearer token: OAuth access token

$env:GOOGLE_OAUTH_ACCESS_TOKEN="ya29...."

Installation

git clone https://github.com/NgoQuocViet2001/google-workspace-mcp.git
cd google-workspace-mcp
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Install from GitHub

Option 1: clone the repository

git clone https://github.com/NgoQuocViet2001/google-workspace-mcp.git
cd google-workspace-mcp
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Option 2: install directly from GitHub

pip install "git+https://github.com/NgoQuocViet2001/google-workspace-mcp.git"

If you install it this way, the console entrypoint is:

google-workspace-mcp

Running the Server

cd 
.venv\Scripts\python.exe mcp_google_workspace.py

Or, if you installed it directly from GitHub:

google-workspace-mcp

To bootstrap OAuth for a private user account:

google-workspace-mcp auth

To inspect the current auth setup:

google-workspace-mcp auth status

Codex MCP Configuration

{
  "mcpServers": {
    "google-workspace": {
      "command": "/.venv/Scripts/python.exe",
      "args": ["/mcp_google_workspace.py"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_SECRETS_FILE": "C:/path/to/oauth-client-secret.json",
        "GOOGLE_OAUTH_TOKEN_FILE": "C:/path/to/oauth-token.json"
      }
    }
  }
}

For public Sheets only, replace the env block with:

{
  "GOOGLE_API_KEY": "your_api_key"
}

If you installed the package directly from GitHub into an environment on your PATH, you can also use:

{
  "mcpServers": {
    "google-workspace": {
      "command": "google-workspace-mcp",
      "env": {
        "GOOGLE_OAUTH_CLIENT_SECRETS_FILE": "C:/path/to/oauth-client-secret.json",
        "GOOGLE_OAUTH_TOKEN_FILE": "C:/path/to/oauth-token.json"
      }
    }
  }
}

Available Tools

• diagnose_google_auth
• resolve_google_file
• read_sheet_values
• read_sheet_grid
• get_sheet_row
• search_sheet
• sheet_to_json
• `ins