Apps Script MCP
by sam-ent
README.md
# Google Automation MCP
[](https://pypi.org/project/google-automation-mcp/) [](https://github.com/sam-ent/google-automation-mcp/actions/workflows/test.yml) [](https://codecov.io/gh/sam-ent/google-automation-mcp)
[](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://modelcontextprotocol.io) [](https://pypi.org/project/google-automation-mcp/) [](https://github.com/astral-sh/ruff)
**Google Workspace APIs for AI agents - no GCP project required.**
Uses [clasp](https://github.com/google/clasp) for authentication. No GCP console, no OAuth consent screen, no client secrets. Just authenticate and go.
## Quick Start
```bash
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](https://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.
| | **Clasp Router** (default) | **REST API** (with OAuth 2.1) |
|---|---|---|
| **Setup time** | ~2 min (browser sign-in + one toggle + one Allow click) | ~15 min (GCP project + enable APIs + OAuth consent screen + credentials) |
| **GCP project** | Not needed | Required |
| **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 |
| **Latency** | ~1-3s per call (Apps Script execution overhead) | ~100-300ms per call |
| **Execution timeout** | 30s per call (Apps Script limit) | No per-call limit |
| **Best for** | Personal use, prototyping, AI agents | High-volume, production, low-latency apps |
### Daily quotas (free consumer Google account)
| Service | Clasp Router (Apps Script limits) | REST API limits |
|---------|----------------------------------|-----------------|
| **Gmail send** | 100 recipients/day | 500 emails/day (Gmail API) |
| **Gmail read** | 50,000 reads/day | 250 quota units/s per user |
| **Drive** | 90 min total runtime/day | 1 billion API calls/day (project) |
| **Sheets** | 90 min total runtime/day | 300 requests/min per project |
| **Calendar** | 5,000 events created/day | 1M queries/day per project |
| **Docs** | 90 min total runtime/day | 300 requests/min per project |
| **Forms** | 90 min total runtime/day | No published limit |
| **Tasks** | Same as REST (calls Tasks API via `UrlFetchApp`) | 50,000 requests/day |
> **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)
### 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:
```bash
export GOOGLE_OAUTH_CLIENT_ID='...'
export GOOGLE_OAUTH_CLIENT_SECRET='...'
gmcp auth --oauth21
```
## Security: AI Never Sees Credentials
| | Direct API | This MCP |
|---|---|---|
| **Credentials** | AI handles tokens directly | AI never sees tokens |
| **API access** | Any endpoint | 60 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 Desktop (One-Click Install):**
Download [`google-automation-mcp.dxt`](https://github.com/sam-ent/google-automation-mcp/releases/latest) and open it. Claude Desktop will install automatically.
**Claude Code** (`~/.mcp.json`):
```json
{
"mcpServers": {
"google": {
"type": "stdio",
"command": "uvx",
"args": ["google-automation-mcp"]
}
}
}
```
**Claude Desktop (Manual)** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"google": {
"command": "uvx",
"args": ["google-automation-mcp"]
}
}
}
```
**Gemini CLI:**
```bash
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:
```python
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:
| 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 |
```python
# 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`)
```bash
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
```bash
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](https://github.com/taylorwilsdon/google_workspace_mcp) by Taylor Wilsdon (MIT License).
## License
MIT
TDQS
B3.4/5.0
Scored across 50 tools
Disambiguation4/5
Most tools are clearly distinct by resource type (Docs, Sheets, Drive, Calendar, Gmail, Scripts) and action (create, get, update, delete, list, search). However, some overlap exists: append_doc_text_tool and modify_doc_text_tool both modify Docs, and append_sheet_values_tool and update_sheet_values_tool both write to Sheets, which could cause confusion without careful reading of descriptions.
Naming Consistency5/5
Tool names follow a highly consistent verb_noun pattern throughout (e.g., create_doc, get_doc_content, update_sheet_values, list_script_projects). All use snake_case with clear, descriptive verbs aligned to CRUD operations, making the set predictable and easy to navigate.
Tool Count2/5
With 50 tools, the count is excessive for a single server, making it overwhelming and difficult for agents to navigate efficiently. While the scope covers multiple Google services (Docs, Sheets, Drive, Calendar, Gmail, Apps Script), the sheer volume suggests poor scoping—many tools could be consolidated or split into focused sub-servers.
Completeness5/5
The tool set provides comprehensive coverage across Google services, including full CRUD operations for Docs, Sheets, Drive files, Calendar events, and Script projects, plus search, listing, and specialized actions like authentication and trigger generation. No obvious gaps exist; agents can perform end-to-end workflows without dead ends.
Maintenance
ActivityInactive
ResponsivenessUnresponsive