gworkspace-mcp
gworkspace-mcp
用于 Google Workspace 自动化的模型上下文协议 (MCP) 服务器:支持 Google Sheets、Apps Script、Drive、Docs、Gmail 和触发器。基于 FastMCP 构建。
专为 Claude Code(或任何兼容 MCP 的客户端)设计,让您可以直接在对话中编辑 Apps Script 项目、操作电子表格、发送电子邮件和管理 Drive 文件。
功能
Apps Script (9 个工具) — 列出、读取、更新、创建、部署和运行 Apps Script 项目。支持细粒度的文件编辑,无需重写整个脚本。
Sheets (10 个工具) — 读取/写入范围、批量更新、格式设置、保护、公式、仪表板。
Drive (4 个工具) — 列出、搜索、移动和管理文件。
Docs (1 个工具) — 读取/编辑 Google Docs。
Gmail (3 个工具) — 撰写并发送电子邮件。
Triggers (3 个工具) — 管理 Apps Script 基于时间和事件的触发器。
Connect (1 个工具) — 将本地 Apps Script 项目绑定到电子表格。
Related MCP server: Google Workspace MCP Server
要求
Python 3.10+
一个已启用以下 API 的 Google Cloud 项目:
Google Sheets API
Google Drive API
Apps Script API
Google Docs API
Gmail API
Google Calendar API
OAuth 2.0 桌面凭据 (
client_secret.json)
安装
git clone https://github.com/LeooNic/gworkspace-mcp.git
cd gworkspace-mcp
pip install -e .或者使用 uv:
uv pip install -e .Google Cloud 设置
前往 console.cloud.google.com 并创建一个项目。
在 API 和服务 → 库 下启用上述 API。
前往 API 和服务 → OAuth 同意屏幕,将其配置为 外部 (External),并将您的 Google 帐户添加为测试用户。
前往 API 和服务 → 凭据 → 创建凭据 → OAuth 客户端 ID,选择 桌面应用 (Desktop app),然后下载 JSON 文件。
通过以下方式之一使凭据对服务器可用:
将 JSON 文件放置在
~/.secrets/gworkspace-mcp/client_secret.json,或者设置
GOOGLE_CLIENT_SECRET_PATH=/full/path/to/client_secret.json,或者将
GOOGLE_OAUTH_CLIENT_ID和GOOGLE_OAUTH_CLIENT_SECRET设置为环境变量。
首次运行工具时,将打开一个浏览器窗口以进行 OAuth 同意。生成的令牌将存储在 ~/.secrets/gworkspace-mcp/token.json 中并自动刷新。
在 Claude Code 中注册
将其添加到您的 Claude Code settings.json(或 ~/.claude.json)中:
{
"mcpServers": {
"gworkspace": {
"command": "gworkspace-mcp"
}
}
}如果 gworkspace-mcp 不在您的 PATH 中,请使用 pip install -e . 创建的可执行文件的绝对路径(在 Windows 上,通常为 C:\Users\<you>\AppData\Local\Programs\Python\Python3XX\Scripts\gworkspace-mcp.exe)。
不安装入口点的替代调用方式:
{
"mcpServers": {
"gworkspace": {
"command": "python",
"args": ["-m", "gworkspace_mcp.server"]
}
}
}OAuth 范围
服务器请求以下范围:
spreadsheets,drive,documents,calendarscript.projects,script.deployments,script.processes,script.metricsgmail.send,gmail.composeuserinfo.email,userinfo.profile
安全说明
您的
client_secret.json和token.json是个人的 — 切勿提交它们。仓库的.gitignore已经排除了它们。令牌存储在
~/.secrets/gworkspace-mcp/下。服务器在本地运行;它不会暴露任何网络端点。
许可证
MIT — 参见 LICENSE。
Available Tools
31 toolsdrive_copyB
Copy a Drive file (spreadsheet, doc, etc). Returns the new file ID and URL.
Inputs: source (required), new_name (required), folder_id. Returns: Generic wrapper for non-object return types.
drive_create_spreadsheetB
Create a new Google Spreadsheet. Returns ID and URL.
Inputs: name (required), folder_id. Returns: Generic wrapper for non-object return types.
drive_moveC
Move a file to a different folder.
Inputs: file_url (required), dest_folder_id (required). Returns: Generic wrapper for non-object return types.
drive_searchB
Search Drive files. Uses Drive query syntax. Examples: "name contains 'report'", "mimeType='application/vnd.google-apps.spreadsheet'".
Inputs: query (required), page_size. Returns: Generic wrapper for non-object return types.
generate_docsB
Generate functional documentation for a spreadsheet project. Analyzes the spreadsheet structure, script functions, triggers, and manifest to produce a complete technical document.
Args: spreadsheet_url: Spreadsheet URL or ID script_url: Optional Apps Script URL or ID output: "sheet" writes a Documentacion tab in the spreadsheet, "text" returns the doc as text
Inputs: spreadsheet_url (required), script_url, output. Returns: Generic wrapper for non-object return types.
script_add_functionC
Add a new function to an existing file. Appends at the end.
Inputs: script_id (required), file_name (required), source (required). Returns: Generic wrapper for non-object return types.
script_create_fileC
Create a new .gs file in the script project.
Inputs: script_id (required), file_name (required), source. Returns: Generic wrapper for non-object return types.
script_delete_functionB
Delete a function from the script project.
Inputs: script_id (required), function_name (required). Returns: Generic wrapper for non-object return types.
script_edit_functionB
Replace a specific function's source code. Only that function is modified.
Inputs: script_id (required), function_name (required), new_source (required). Returns: Generic wrapper for non-object return types.
script_get_fileC
Get the full source code of a file in the script project.
Inputs: script_id (required), file_name (required). Returns: Generic wrapper for non-object return types.
script_get_functionB
Get the source code of a specific function by name.
Inputs: script_id (required), function_name (required). Returns: Generic wrapper for non-object return types.
script_list_functionsB
List all functions in a script project with their file, signature, and line numbers.
Inputs: script_id (required). Returns: Generic wrapper for non-object return types.
script_runB
Execute a function in a deployed script. Requires API Executable deployment.
Inputs: script_id (required), function_name (required), parameters. Returns: Generic wrapper for non-object return types.
script_update_fileB
Replace the entire content of a file in the script project.
Inputs: script_id (required), file_name (required), source (required). Returns: Generic wrapper for non-object return types.
send_emailB
Send an email via Gmail. Set html=True for HTML body. cc/bcc are comma-separated email addresses.
Inputs: to (required), subject (required), body (required), html, +2 more. Returns: Generic wrapper for non-object return types.
send_email_previewA
Preview an email without sending it. Returns the formatted message.
Inputs: to (required), subject (required), body (required), html. Returns: Generic wrapper for non-object return types.
send_html_emailC
Send an HTML email with optional plain-text fallback.
Inputs: to (required), subject (required), html_body (required), plain_fallback, +1 more. Returns: Generic wrapper for non-object return types.
sheets_add_tableB
Create a Google Sheets Table (the structured table feature, Ctrl+Alt+T). Converts a data range into a formal table with headers, banding, and filtering.
Inputs: spreadsheet (required), sheet_name (required), range_a1 (required), name. Returns: Generic wrapper for non-object return types.
sheets_add_validationC
Add data validation. validation_type: DROPDOWN, CHECKBOX, NUMBER, DATE. For DROPDOWN, pass values as list of options.
Inputs: spreadsheet (required), sheet_name (required), range_a1 (required), validation_type (required), +1 more. Returns: Generic wrapper for non-object return types.
sheets_appendC
Append rows to the end of a sheet.
Inputs: spreadsheet (required), range (required), values (required). Returns: Generic wrapper for non-object return types.
sheets_conditional_formatC
Add conditional formatting. rule_type: NUMBER_GREATER, NUMBER_LESS, NUMBER_EQ, TEXT_CONTAINS, TEXT_NOT_CONTAINS, CUSTOM_FORMULA. For CUSTOM_FORMULA, condition_value is the formula (e.g., '=A1>8').
Inputs: spreadsheet (required), sheet_name (required), range_a1 (required), rule_type (required), +2 more. Returns: Generic wrapper for non-object return types.
sheets_copy_sheetC
Copy a sheet from one spreadsheet to another.
Inputs: source_spreadsheet (required), sheet_name (required), dest_spreadsheet (required). Returns: Generic wrapper for non-object return types.
sheets_describeB
Get full structure of a spreadsheet: sheets, named ranges, protected ranges.
Inputs: spreadsheet (required). Returns: Generic wrapper for non-object return types.
sheets_formatC
Format a range. Colors as hex (#RRGGBB). h_align: LEFT/CENTER/RIGHT.
Inputs: spreadsheet (required), sheet_name (required), range_a1 (required), bold, +6 more. Returns: Generic wrapper for non-object return types.
sheets_protectC
Protect a sheet or range. If range_a1 is None, protects the entire sheet.
Inputs: spreadsheet (required), sheet_name (required), range_a1, description, +1 more. Returns: Generic wrapper for non-object return types.
sheets_readC
Read values from a sheet. Pass spreadsheet URL or ID.
Inputs: spreadsheet (required), range (required), render. Returns: Generic wrapper for non-object return types.
sheets_writeC
Write values to a sheet range. values is a 2D array.
Inputs: spreadsheet (required), range (required), values (required). Returns: Generic wrapper for non-object return types.
trigger_create_time_drivenB
Create a time-driven trigger via Apps Script execution. Generates and runs trigger setup code in the script.
Options:
every_minutes: 1, 5, 10, 15, 30
every_hours: 1, 2, 4, 6, 8, 12
day_of_week + hour: weekly trigger (MONDAY-SUNDAY, hour 0-23)
hour only: daily trigger at that hour
Inputs: script_id (required), function_name (required), every_minutes, every_hours, +2 more. Returns: Generic wrapper for non-object return types.
trigger_deleteA
Delete a trigger by ID. Use trigger_list to find IDs.
Inputs: script_id (required), trigger_id (required). Returns: Generic wrapper for non-object return types.
trigger_listB
List all triggers for a script project.
Inputs: script_id (required). Returns: Generic wrapper for non-object return types.
workspace_connectA
Connect to a Google Spreadsheet and discover everything about it.
Args: spreadsheet_url: Spreadsheet URL or ID script_url: Optional. The Apps Script URL or ID (from Extensions > Apps Script). Container-bound scripts don't appear in Drive API (Google limitation), so pass the script URL for full discovery. If omitted, only sheet structure is returned.
Returns: sheet structure, and if script_url is provided: all files with functions, triggers, and deployments.
Inputs: spreadsheet_url (required), script_url. Returns: Generic wrapper for non-object return types.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 31 tools
Most tools have distinct purposes, but some overlap exists. For example, send_email and send_html_email could be confused, and drive_copy/drive_move have similar file manipulation functions. However, clear descriptions help differentiate them.
Tool names follow a consistent snake_case pattern with clear verb_noun conventions. Drive tools use drive_ prefix, script tools use script_ prefix, sheets tools use sheets_ prefix, and email/trigger/workspace tools follow similar patterns. No mixing of conventions.
31 tools is excessive for a single MCP server. While the domain (Google Workspace automation) is broad, this feels like multiple servers combined. A more focused scope with 15-20 tools would be more manageable for agents.
The tool surface provides comprehensive coverage for Google Workspace automation. It includes full CRUD operations for Drive files, Sheets manipulation, Apps Script development, email sending, and trigger management. The workspace_connect tool provides excellent discovery capabilities.
Maintenance
Related MCP Connectors
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Hosted Google Sheets MCP server, with each action switched on or off per account.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP server that enables interaction with Google Sheets through natural language, allowing users to create, read, update, and manage spreadsheet data via the Google Sheets API v4.-
- AlicenseNot gradedqualityDmaintenanceA comprehensive MCP server integrating Google Docs, Sheets, Drive, Gmail, Calendar, and Apps Script APIs, featuring unique Apps Script support for AI-driven automation.9MIT
- AlicenseAqualityBmaintenanceMCP server integrating multiple Google Workspace services including Gmail, Calendar, Drive, Sheets, Docs, Tasks, People, Forms, and Slides, enabling users to manage emails, events, files, documents, and more through natural language.15MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for Google Sheets operations, enabling spreadsheet management including reading, writing, appending, creating, and searching sheets via natural language.MIT