Google MCP

Google

Google's MCP family — wire BigQuery, Cloud SQL, Firestore, Maps, Drive, Gmail, Calendar into your LLM client. Each sub-service has slightly different auth (service account JSON / API key / OAuth), but they all share one rule: credentials stay on your machine.

OAuth requiredAdvanced setup

Why client-side

GCP service account JSONs, API keys, and OAuth tokens are all high-sensitivity — they can reach into your GCP project or Google account. twinkle-hub does not store any of these. This guide walks the three most common sub-services (BigQuery / Maps / Drive); others follow the same pattern.

Prerequisites

Node.js ≥ 18
Your GCP project (BigQuery) / Google account (Drive) / Google Maps API enabled
MCP-capable client

BigQuery — service account JSON

Query BigQuery datasets in your GCP project for ad-hoc SQL analysis.

BigQuery MCP has no official Google npm package yet. We use the actively-maintained community @channel.io/bigquery-mcp below. Other options at https://github.com/google/mcp or via npm search "bigquery mcp".

1https://console.cloud.google.com/iam-admin/serviceaccounts → pick the project
2Create Service Account, name it "claude-mcp"
3Grant roles: BigQuery Data Viewer (read-only) + BigQuery Job User (run queries)
4Click the SA → Keys → Add Key → JSON
5Download to your machine (e.g. ~/.config/gcp/claude-mcp-sa.json), chmod 600

Claude Desktop (macOS)

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "bigquery": {
      "command": "npx",
      "args": ["-y", "@channel.io/bigquery-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "</path/to/your/sa.json>",
        "GCP_PROJECT_ID": "<your-gcp-project-id>"
      }
    }
  }
}

Google Maps — API key

Geocoding, Places, Directions API — POI lookup, distance, coordinate conversion.

1https://console.cloud.google.com/google/maps-apis/credentials
2Create credentials → API key
3Restrict the key: tick IP restriction (your local IP) + the APIs you want (Geocoding / Places / Directions / etc.)
4Copy the key (starts with AIza)

Claude Desktop (macOS)

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-google-maps"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "<your_google_maps_api_key>"
      }
    }
  }
}

Google Drive — OAuth 2.0

Read your Drive files, Docs, Sheets. First run pops a browser for the OAuth dance.

1https://console.cloud.google.com/apis/credentials → Create OAuth client ID → Type: Desktop app
2Download credentials.json (contains client_id + client_secret)
3First MCP run opens a browser for OAuth → you grant access → token saved locally
4Revoke at https://myaccount.google.com/permissions

Claude Desktop (macOS)

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "google-drive": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-gdrive"],
      "env": {
        "GDRIVE_CREDENTIALS_PATH": "</path/to/credentials.json>",
        "GDRIVE_OAUTH_PATH": "</path/to/gdrive-token.json>"
      }
    }
  }
}

Troubleshooting

Symptom	Fix
403 Forbidden on BigQuery	SA role insufficient, or BigQuery API not enabled on the project
OAuth callback failed	OAuth client redirect URI must include http://localhost:port/oauth2callback. Pick Desktop app type.
Maps REQUEST_DENIED	API key restrictions too tight (IP wrong / API not enabled)
Self-signed cert	Corporate proxy may MITM google APIs. Trust the cert chain or change network.

Security notes

Service account JSON contains a private key — treat it like a password. chmod 600, never in git
Restrict API keys to your local IP — limits blast radius if leaked
OAuth tokens auto-refresh; periodically audit https://myaccount.google.com/permissions
Use minimum-privilege roles for the LLM SA (don't grant Owner)