{
  "markdown": "# Google Automation MCP\n\n[![PyPI](https://img.shields.io/pypi/v/google-automation-mcp)](https://pypi.org/project/google-automation-mcp/) [![Tests](https://github.com/sam-ent/google-automation-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/sam-ent/google-automation-mcp/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/sam-ent/google-automation-mcp/graph/badge.svg)](https://codecov.io/gh/sam-ent/google-automation-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/) [![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io) [![Downloads](https://img.shields.io/pypi/dm/google-automation-mcp)](https://pypi.org/project/google-automation-mcp/) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n\n**Google Workspace APIs for AI agents - no GCP project required.**\n\nUses [clasp](https://github.com/google/clasp) for authentication. No GCP console, no OAuth consent screen, no client secrets. Just authenticate and go.\n\n## Quick Start\n\n```bash\nuvx google-automation-mcp auth   # 1. Browser sign-in via clasp\nuvx google-automation-mcp        # 4. Run server\n```\n\nFirst run walks you through three one-time steps:\n\n1. **`gmcp auth`** - opens browser for Google sign-in (clasp OAuth)\n2. **Enable Apps Script API** - `gmcp auth` checks and prompts you to toggle ON at https://script.google.com/home/usersettings (5 seconds)\n3. **Authorize scopes** - `gmcp auth` deploys a Web App router and prints a URL. Open it, click \"Allow\" to grant Gmail/Drive/Sheets/Calendar/Docs/Forms/Tasks access\n4. **Done** - run `gmcp` or `uvx google-automation-mcp` to start the server\n\nCheck status anytime: `gmcp status`\n\n> **Tip:** Use the short alias `gmcp` after installing.\n\n> **Re-authorization:** If a future update adds new scopes, revoke the app at [myaccount.google.com/permissions](https://myaccount.google.com/permissions) (find \"MCP-Router\"), then visit the Web App URL again from `gmcp status`.\n\n## Clasp Router vs REST API\n\nWorkspace tools (Gmail, Drive, Sheets, etc.) can operate in two modes. The clasp router is the default and requires no GCP project. Traditional Google API setup requires creating a GCP project, enabling APIs, configuring an OAuth consent screen, adding test users, and creating credentials.\n\n| | **Clasp Router** (default) | **REST API** (with OAuth 2.1) |\n|---|---|---|\n| **Setup time** | ~2 min (browser sign-in + one toggle + one Allow click) | ~15 min (GCP project + enable APIs + OAuth consent screen + credentials) |\n| **GCP project** | Not needed | Required |\n| **How it works** | Deploys an Apps Script Web App per user; tool calls routed via HTTP POST | Calls Google REST APIs directly with OAuth tokens |\n| **Latency** | ~1-3s per call (Apps Script execution overhead) | ~100-300ms per call |\n| **Execution timeout** | 30s per call (Apps Script limit) | No per-call limit |\n| **Best for** | Personal use, prototyping, AI agents | High-volume, production, low-latency apps |\n\n### Daily quotas (free consumer Google account)\n\n| Service | Clasp Router (Apps Script limits) | REST API limits |\n|---------|----------------------------------|-----------------|\n| **Gmail send** | 100 recipients/day | 500 emails/day (Gmail API) |\n| **Gmail read** | 50,000 reads/day | 250 quota units/s per user |\n| **Drive** | 90 min total runtime/day | 1 billion API calls/day (project) |\n| **Sheets** | 90 min total runtime/day | 300 requests/min per project |\n| **Calendar** | 5,000 events created/day | 1M queries/day per project |\n| **Docs** | 90 min total runtime/day | 300 requests/min per project |\n| **Forms** | 90 min total runtime/day | No published limit |\n| **Tasks** | Same as REST (calls Tasks API via `UrlFetchApp`) | 50,000 requests/day |\n\n> **Note:** Apps Script runtime limits are shared across all services. The 90 min/day limit applies to total execution time, not per-service. At ~2s per call, that's ~2,700 tool calls/day. [Full Apps Script quotas](https://developers.google.com/apps-script/guides/services/quotas)\n\n### Backend selection\n\nThe backend is selected automatically: if `GOOGLE_OAUTH_CLIENT_ID` and `GOOGLE_OAUTH_CLIENT_SECRET` are set, REST APIs are used. Otherwise, the clasp router handles Workspace calls.\n\nOverride with `MCP_USE_ROUTER=true` or `MCP_USE_ROUTER=false` to force a specific backend.\n\nFor multi-user production deployments requiring your own OAuth credentials:\n\n```bash\nexport GOOGLE_OAUTH_CLIENT_ID='...'\nexport GOOGLE_OAUTH_CLIENT_SECRET='...'\ngmcp auth --oauth21\n```\n\n## Security: AI Never Sees Credentials\n\n| | Direct API | This MCP |\n|---|---|---|\n| **Credentials** | AI handles tokens directly | AI never sees tokens |\n| **API access** | Any endpoint | 60 curated tools only |\n| **Audit** | Build your own | Every tool call logged |\n\nThe MCP acts as a security boundary. Your AI agent calls tools; the MCP handles authentication internally.\n\n## MCP Client Configuration\n\n**Claude Desktop (One-Click Install):**\n\nDownload [`google-automation-mcp.dxt`](https://github.com/sam-ent/google-automation-mcp/releases/latest) and open it. Claude Desktop will install automatically.\n\n**Claude Code** (`~/.mcp.json`):\n```json\n{\n  \"mcpServers\": {\n    \"google\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"google-automation-mcp\"]\n    }\n  }\n}\n```\n\n**Claude Desktop (Manual)** (`claude_desktop_config.json`):\n```json\n{\n  \"mcpServers\": {\n    \"google\": {\n      \"command\": \"uvx\",\n      \"args\": [\"google-automation-mcp\"]\n    }\n  }\n}\n```\n\n**Gemini CLI:**\n```bash\ngemini extensions install github:sam-ent/google-automation-mcp\n```\n\n## Available Tools (60)\n\n### Gmail (5)\n`search_gmail_messages` · `get_gmail_message` · `send_gmail_message` · `list_gmail_labels` · `modify_gmail_labels`\n\n### Drive (10)\n`search_drive_files` · `list_drive_items` · `get_drive_file_content` · `create_drive_file` · `create_drive_folder` · `delete_drive_file` · `trash_drive_file` · `share_drive_file` · `list_drive_permissions` · `remove_drive_permission`\n\n### Sheets (6)\n`list_spreadsheets` · `get_sheet_values` · `update_sheet_values` · `append_sheet_values` · `create_spreadsheet` · `get_spreadsheet_metadata`\n\n### Calendar (5)\n`list_calendars` · `get_events` · `create_event` · `update_event` · `delete_event`\n\n### Docs (5)\n`get_doc_content` · `search_docs` · `create_doc` · `modify_doc_text` · `append_doc_text`\n\n### Forms (4)\n`get_form` · `create_form` · `add_form_question` · `get_form_responses`\n\n### Tasks (6)\n`list_task_lists` · `get_tasks` · `create_task` · `update_task` · `delete_task` · `complete_task`\n\n### Apps Script (17)\n`list_script_projects` · `get_script_project` · `get_script_content` · `create_script_project` · `update_script_content` · `delete_script_project` · `run_script_function` · `create_deployment` · `list_deployments` · `update_deployment` · `delete_deployment` · `list_versions` · `create_version` · `get_version` · `list_script_processes` · `get_script_metrics` · `generate_trigger_code`\n\n### Auth (2)\n`start_google_auth` · `complete_google_auth`\n\n## Multi-User Support\n\nAll tools accept `user_google_email` for per-user credential isolation:\n\n```python\nsearch_gmail_messages(user_google_email=\"alice@example.com\", query=\"is:unread\")\nsearch_gmail_messages(user_google_email=\"bob@example.com\", query=\"is:unread\")\n```\n\nCredentials stored separately: `~/.secrets/google-automation-mcp/credentials/{email}.json`\n\n## Apps Script: Extending Google Workspace\n\nApps Script tools let you deploy code that runs inside Google apps - things REST APIs cannot do:\n\n| Capability | Example |\n|------------|---------|\n| Custom spreadsheet functions | `=VALIDATE_EMAIL(A1)` in cells |\n| Real-time triggers | `onEdit`, `onOpen` |\n| Custom menus | Add menu items to Sheets/Docs |\n| Webhooks | `doGet`/`doPost` handlers |\n\n```python\n# Create a bound script with custom function\ncreate_script_project(title=\"Validator\", parent_id=\"SPREADSHEET_ID\")\nupdate_script_content(script_id=\"...\", files=[{\n    \"name\": \"Code\",\n    \"type\": \"SERVER_JS\",\n    \"source\": \"function VALIDATE_EMAIL(e) { return /^[^@]+@[^@]+\\\\.[^@]+$/.test(e); }\"\n}])\n```\n\n## Limitations\n\n**`run_script_function`** requires one-time setup per script: Open script at script.google.com -> Project Settings -> Change GCP project -> Deploy as API Executable. Once configured, functions can be called repeatedly. All other tools work without this setup.\n\n## CLI Reference\n\nShort alias: `gmcp` (or full name: `google-automation-mcp`)\n\n```bash\ngmcp                 # Run server\ngmcp setup           # Interactive setup wizard\ngmcp auth            # Authenticate with clasp\ngmcp auth --oauth21  # OAuth 2.1 for production\ngmcp status          # Check auth status\ngmcp version         # Show version\n```\n\n## Development\n\n```bash\ngit clone https://github.com/sam-ent/google-automation-mcp.git\ncd google-automation-mcp\nuv sync\nuv run pytest tests/ -v  # 183 tests\n```\n\n## Acknowledgments\n\nBuilt on [google_workspace_mcp](https://github.com/taylorwilsdon/google_workspace_mcp) by Taylor Wilsdon (MIT License).\n\n## License\n\nMIT\n",
  "bytes": 9269,
  "sha": "b1a12637b6f7462e7cc43f5937ba148877ddb7e0e6a0c0d3c1fd8a708d081a55",
  "repo_slug": "sam-ent/google-automation-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_sam_ent_google_automation_mcp_544d14ec/readme"
}