google-automation-mcp 0.5.1

Headless Google Workspace automation for AI - Apps Script, Gmail, Drive, Sheets, Calendar, Docs

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        # Run server
uvx google-automation-mcp auth   # Authenticate (one-time browser sign-in)

That's it. No GCP project setup. Tokens auto-refresh after initial auth.

Tip: Use the short alias gmcp after installing.

Why No GCP Project?

Traditional Google API setup requires:

1. Create GCP project
2. Enable APIs
3. Configure OAuth consent screen
4. Add test users
5. Create OAuth credentials
6. Download client_secret.json

This MCP uses clasp (Google's official Apps Script CLI) which handles OAuth without a GCP project. Same Google authentication, zero configuration.

Security: AI Never Sees Credentials

	Direct API	This MCP
Credentials	AI handles tokens directly	AI never sees tokens
API access	Any endpoint	50 curated tools only
Audit	Build your own	Every tool call logged

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

MCP Client Configuration

Claude Code (~/.mcp.json):

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

Claude Desktop (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 (50)

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

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="[e-mail]", query="is:unread")
search_gmail_messages(user_google_email="[e-mail]", 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:

Capability	Example
Custom spreadsheet functions	=VALIDATE_EMAIL(A1) in cells
Real-time triggers	onEdit, onOpen
Custom menus	Add menu items to Sheets/Docs
Webhooks	doGet/doPost handlers

# 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 manual setup: Open script at script.google.com → Project Settings → Change GCP project → Deploy as API Executable. All other tools work without this.

API quotas: Google enforces rate limits.

Production: OAuth 2.1

For multi-user deployments requiring your own OAuth credentials:

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

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  # 45 tests

Acknowledgments

Built on google_workspace_mcp by Taylor Wilsdon (MIT License).

License

MIT