Google Automation MCP

Google Workspace APIs for AI agents - no GCP project required.

Uses clasp for authentication. No GCP console, no OAuth consent screen, no client secrets. Just authenticate and go.

Quick Start

uvx google-automation-mcp auth   # 1. Browser sign-in via clasp
uvx google-automation-mcp        # 4. Run server

First run walks you through three one-time steps:

1. gmcp auth - opens browser for Google sign-in (clasp OAuth)

2. Enable Apps Script API - gmcp auth checks and prompts you to toggle ON at https://script.google.com/home/usersettings (5 seconds)

3. 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

4. Done - run gmcp or uvx google-automation-mcp to start the server

Check status anytime: gmcp status

Tip: Use the short alias gmcp after installing.

Re-authorization: If a future update adds new scopes, revoke the app at myaccount.google.com/permissions (find "MCP-Router"), then visit the Web App URL again from gmcp status.

Clasp Router vs REST API

Workspace 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.

Daily quotas (free consumer Google account)

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

Backend selection

The 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.

Override with MCP_USE_ROUTER=true or MCP_USE_ROUTER=false to force a specific backend.

For multi-user production deployments requiring your own OAuth credentials:

export GOOGLE_OAUTH_CLIENT_ID='...'
export GOOGLE_OAUTH_CLIENT_SECRET='...'
gmcp auth --oauth21

Security: AI Never Sees Credentials

The MCP acts as a security boundary. Your AI agent calls tools; the MCP handles authentication internally.

MCP Client Configuration

Claude Desktop (One-Click Install):

Download google-automation-mcp.dxt and open it. Claude Desktop will install automatically.

Claude Code (~/.mcp.json):

{
  "mcpServers": {
    "google": {
      "type": "stdio",
      "command": "uvx",
      "args": ["google-automation-mcp"]
    }
  }
}

Claude Desktop (Manual) (claude_desktop_config.json):

{
  "mcpServers": {
    "google": {
      "command": "uvx",
      "args": ["google-automation-mcp"]
    }
  }
}

Gemini CLI:

gemini extensions install github:sam-ent/google-automation-mcp

Available Tools (60)

Gmail (5)

search_gmail_messages · get_gmail_message · send_gmail_message · list_gmail_labels · modify_gmail_labels

Drive (10)

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

Sheets (6)

list_spreadsheets · get_sheet_values · update_sheet_values · append_sheet_values · create_spreadsheet · get_spreadsheet_metadata

Calendar (5)

list_calendars · get_events · create_event · update_event · delete_event

Docs (5)

get_doc_content · search_docs · create_doc · modify_doc_text · append_doc_text

Forms (4)

get_form · create_form · add_form_question · get_form_responses

Tasks (6)

list_task_lists · get_tasks · create_task · update_task · delete_task · complete_task

Apps Script (17)

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

Auth (2)

start_google_auth · complete_google_auth

Multi-User Support

All tools accept user_google_email for per-user credential isolation:

search_gmail_messages(user_google_email="alice@example.com", query="is:unread")
search_gmail_messages(user_google_email="bob@example.com", query="is:unread")

Credentials stored separately: ~/.secrets/google-automation-mcp/credentials/{email}.json

Apps Script: Extending Google Workspace

Apps Script tools let you deploy code that runs inside Google apps - things REST APIs cannot do:

# Create a bound script with custom function
create_script_project(title="Validator", parent_id="SPREADSHEET_ID")
update_script_content(script_id="...", files=[{
    "name": "Code",
    "type": "SERVER_JS",
    "source": "function VALIDATE_EMAIL(e) { return /^[^@]+@[^@]+\\.[^@]+$/.test(e); }"
}])

Limitations

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.

CLI Reference

Short alias: gmcp (or full name: google-automation-mcp)

gmcp                 # Run server
gmcp setup           # Interactive setup wizard
gmcp auth            # Authenticate with clasp
gmcp auth --oauth21  # OAuth 2.1 for production
gmcp status          # Check auth status
gmcp version         # Show version

Development

git clone https://github.com/sam-ent/google-automation-mcp.git
cd google-automation-mcp
uv sync
uv run pytest tests/ -v  # 183 tests

Acknowledgments

Built on google_workspace_mcp by Taylor Wilsdon (MIT License).

License

MIT