Google 自动化 MCP

面向 AI 代理的 Google Workspace API - 无需 GCP 项目。

使用 clasp 进行身份验证。无需 GCP 控制台，无需 OAuth 同意屏幕，无需客户端密钥。只需验证即可使用。

快速入门

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

首次运行将引导您完成三个一次性步骤：

1. gmcp auth - 打开浏览器进行 Google 登录 (clasp OAuth)

2. 启用 Apps Script API - gmcp auth 会检查并提示您在 https://script.google.com/home/usersettings 处将其开启（5 秒钟）

3. 授权范围 - gmcp auth 会部署一个 Web App 路由器并打印一个 URL。打开它，点击“允许”以授予 Gmail/Drive/Sheets/Calendar/Docs/Forms/Tasks 的访问权限

4. 完成 - 运行 gmcp 或 uvx google-automation-mcp 以启动服务器

随时检查状态：gmcp status

提示： 安装后使用短别名 gmcp。

重新授权： 如果未来的更新添加了新范围，请在 myaccount.google.com/permissions 处撤销该应用（查找“MCP-Router”），然后再次访问 gmcp status 提供的 Web App URL。

Clasp 路由器与 REST API

Workspace 工具（Gmail、Drive、Sheets 等）可以在两种模式下运行。Clasp 路由器是默认模式，不需要 GCP 项目。传统的 Google API 设置需要创建 GCP 项目、启用 API、配置 OAuth 同意屏幕、添加测试用户并创建凭据。

每日配额（免费个人 Google 账户）

注意： Apps Script 运行时间限制在所有服务之间共享。90 分钟/天的限制适用于总执行时间，而非每个服务。按每次调用约 2 秒计算，每天约为 2,700 次工具调用。完整的 Apps Script 配额

后端选择

后端会自动选择：如果设置了 GOOGLE_OAUTH_CLIENT_ID 和 GOOGLE_OAUTH_CLIENT_SECRET，则使用 REST API。否则，clasp 路由器处理 Workspace 调用。

使用 MCP_USE_ROUTER=true 或 MCP_USE_ROUTER=false 覆盖以强制指定后端。

对于需要您自己 OAuth 凭据的多用户生产部署：

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

安全性：AI 永远看不到凭据

MCP 充当安全边界。您的 AI 代理调用工具；MCP 在内部处理身份验证。

MCP 客户端配置

Claude Desktop (一键安装)：

下载 google-automation-mcp.dxt 并打开它。Claude Desktop 将自动安装。

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

可用工具 (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

多用户支持

所有工具都接受 user_google_email 以实现用户间的凭据隔离：

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

凭据单独存储：~/.secrets/google-automation-mcp/credentials/{email}.json

Apps Script：扩展 Google Workspace

Apps Script 工具允许您部署在 Google 应用内运行的代码 - 这是 REST API 无法做到的：

# 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); }"
}])

限制

run_script_function 需要每个脚本进行一次性设置：在 script.google.com 打开脚本 -> 项目设置 -> 更改 GCP 项目 -> 部署为 API 可执行文件。配置完成后，即可重复调用函数。所有其他工具无需此设置即可工作。

CLI 参考

短别名：gmcp (或全名：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

开发

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

致谢

基于 Taylor Wilsdon 的 google_workspace_mcp 构建 (MIT 许可证)。

许可证

MIT