This server is a production-oriented MCP interface to Google Workspace, integrating Gmail, Calendar, Drive, Sheets, Docs, Tasks, People, Forms, Slides, and optional Keep, Chat, Meet, Gemini. It enables AI agents to connect, manage, and automate workflows across these services with features like incremental OAuth consent, cross-service search, stable resource resolution, a prepare/commit safety protocol for high-impact actions, file upload management, and dynamic tool discovery.
Core Capabilities:
Authentication & Connection Management: Initiate OAuth flow with incremental capability requests (connect_google_workspace), check connection status (get_google_connection_status), disconnect (disconnect_google_workspace), and refresh the tool catalog after consent changes (refresh_workspace_catalog).
Workspace Overview & Discovery: Inspect enabled namespaces and OAuth scopes (get_workspace_capabilities), perform unified search across Drive, People, and Gmail (search_workspace), resolve stable resource URIs to fresh metadata (resolve_workspace_resource), and diagnose the file-picker UI (get_mcp_apps_diagnostics).
File Management: Upload and manage files via an interactive file-picker UI (files_file_manager), list uploaded files (files_list_files, files_list_files_page), and use file handles across Gmail, Drive, and Gemini tools.
Safe Execution of Consequential Actions: Preview the impact of high-risk operations and obtain a one-time token (prepare_workspace_action), then execute atomically (commit_workspace_action).
Tool Discovery: Search the tool catalog using natural language (search_tools) and call tools dynamically by name (call_tool).
Service Integrations (when mounted):
Gmail: Send, read, search, manage labels, drafts, threads, filters, forwarding, vacation settings, and batch operations.
Google Calendar: CRUD events, check availability, find common free slots, manage attachments and conferencing, conflict prevention.
Google Drive: CRUD files/folders, upload/download/export, manage sharing, shared drives, progress reporting.
Google Sheets: Read/write values, batch updates.
Google Docs: Fetch/create, text mutations, batch updates.
Google Tasks: Manage task lists and tasks, complete/move/delete.
Google People: Manage contacts and contact groups.
Google Forms: Create/update forms, manage publishing, read responses.
Google Slides: Manage presentations, slide pages, text replacement, batch updates.
Optional Integrations (feature-flagged):
Google Keep: CRUD notes, share, summarize.
Google Chat: Read/post messages, summarize spaces.
Google Meet: Create/manage meeting spaces, conference records.
Gemini: Generate/edit images, analyze video/audio; supports file inputs.
MCP Apps Dashboard: Interactive weekly calendar, inbox summary, email detail, scheduling (when enabled).
Allows sending, reading, searching emails, managing labels, attachments, drafts, threads, filters, forwarding, vacation settings, and summarizing emails.
Provides tools for managing events, calendars, availability checks, smart scheduling, event attachments, and conflict prevention.
Integration for Google Chat (optional, requires enabling).
Allows fetching and creating documents, appending and replacing text, and raw batch updates.
Provides file/folder CRUD, uploads, downloads, exports, sharing permissions, and Shared Drives operations.
Allows creating, reading, updating forms, managing publish settings, and reading responses.
Integration for Google Keep (optional, requires enabling).
Integration for Google Meet (optional, requires enabling).
Provides spreadsheet metadata, reading/writing values, appending, and raw batch updates.
Allows creating and modifying presentations, slide pages, thumbnails, text replacement, and raw batch updates.
Manages task lists and tasks, including creation, completion, movement, and deletion.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-google-workspace schedule a meeting with Sarah for next Tuesday at 2pm"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Production-oriented Google Workspace MCP package with:
Gmail MCP: send/read/search emails, attachment handling, label management, batch operations.
Google Calendar MCP: events, availability, create/update/delete operations.
Google Drive MCP: files/folders CRUD, uploads/downloads/exports, sharing permissions, Shared Drives operations.
Google Sheets MCP: spreadsheet metadata, values reads/writes, and raw batch updates.
Google Docs MCP: document fetch/create flows plus convenience text mutations and raw batch updates.
Google Tasks MCP: task lists, tasks, completion, movement, and deletion.
Google People MCP: personal contacts and contact groups.
Google Forms MCP: forms CRUD, publish settings, and response reads.
Google Slides MCP: presentations, slide pages, thumbnails, text replacement, and raw batch updates.
MCP Apps Dashboard: workspace dashboard app-layer tools/resources with interactive UI.
Optional Google Keep MCP, Google Chat MCP, Google Meet MCP, and Gemini media integrations behind feature flags.
FastMCP advanced features: Context logging, progress updates, user elicitation, sampling, resources, and prompts.
Composed server architecture: Gmail + Calendar + Drive + Sheets + Docs + Tasks + People + Forms + Slides mounted by default, with optional Apps/Keep/Chat/Meet/Gemini namespaces.
Python 3.12+
UV package manager
Node.js 18+ and npm (required for MCP Apps UI in src/mcp_google_workspace/apps/ui)
Google Cloud OAuth desktop credentials (credentials.json)
Google APIs enabled in your Google Cloud project: Gmail, Calendar, Drive, Sheets, Docs, Tasks, People, Forms, and Slides
Optional APIs when enabling feature-flagged integrations: Google Keep, Google Chat, and Google Meet
Gemini Developer API key when enabling Gemini media tools
Related MCP server: Google Workspace MCP Server
uv sync --all-extras --devIf you are working on MCP Apps UI, install frontend dependencies and build the bundle:
cd src/mcp_google_workspace/apps/ui
npm ci
npm run buildPlace the Google OAuth client credentials.json in one of:
project root: ./credentials.json
package credentials folder: ./src/credentials/credentials.json
Configure a versioned Fernet key ring before first use. Production deployments should mount a secret-manager document through MCP_SECRET_FILE; MCP_TOKEN_ENCRYPTION_KEY remains a single-key development option. The MCP encrypts each user's refresh token separately and never writes a shared token.json.
Generate a key once and store it in your secret manager:
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"Mounted secret document:
{
"active_token_encryption_key_id": "2026-07",
"token_encryption_keys": {
"2026-07": "<active Fernet key>",
"2026-04": "<retained previous Fernet key>"
}
}Reads accept retained keys and rewrite ciphertext with the active key. Remove an old key only after a rotation/restore drill confirms all durable records have been rewritten.
Sheets, Docs, Tasks, People, Forms, and Slides are mounted by default and their scopes are always requested. When scopes change, reconnect the affected user so their encrypted per-user token receives the expanded grant.
Google Keep OAuth scope can return invalid_scope in standard user OAuth flows.
Keep integration is therefore disabled by default.
Enable Keep when your Google Workspace setup supports it:
$env:ENABLE_KEEP="true"Google Chat OAuth scopes also commonly require Google Workspace accounts. Chat integration is therefore disabled by default.
Enable Chat when your Google Workspace setup supports it:
$env:ENABLE_CHAT="true"Google Meet integration is also disabled by default. Enable it only after enabling the Meet API for the same OAuth client:
$env:ENABLE_MEET="true"Gemini media integration is also disabled by default. Enable it with a Gemini Developer API key:
$env:ENABLE_GEMINI="true"
$env:GEMINI_API_KEY="your-api-key"Capability-specific Gemini model defaults:
$env:GEMINI_IMAGE_GENERATE_MODEL="gemini-3.1-flash-image-preview"
$env:GEMINI_IMAGE_EDIT_MODEL="gemini-3.1-flash-image-preview"
$env:GEMINI_VIDEO_UNDERSTANDING_MODEL="gemini-3-flash-preview"
$env:GEMINI_AUDIO_UNDERSTANDING_MODEL="gemini-3-flash-preview"
$env:GEMINI_REASONING_MODEL="gemini-3.1-pro-preview"Whenever you enable an optional integration or otherwise change scopes, reconnect each affected user.
The MCP app-layer dashboard namespace is opt-in for controlled rollout.
Enable apps namespace:
$env:ENABLE_APPS_DASHBOARD="true"uv run python -m mcp_google_workspaceThis repository now includes a native uv-based MCP Bundle manifest and packaging assets.
Install on Claude Desktop:
Download the latest .mcpb from GitHub Releases.
In Claude Desktop, open the MCP bundle install flow.
Select the downloaded mcp-google-workspace-*.mcpb file.
Choose the credentials directory that contains credentials.json, or leave it empty to use the repo defaults.
Enable optional integrations only if your Google Workspace account and OAuth client support their scopes.
Finish the install and authenticate in the browser on first launch.
Gemini media tools are API-key-based rather than OAuth-based. If you enable Gemini in the bundle UI, also set the Gemini API key and optional model defaults there.
Build a local .mcpb archive only if you are developing or testing bundle changes:
uv run python scripts/build_mcpb.pyThe packaging command runs npm ci and rebuilds the Apps UI from the exact
frontend lock before creating the archive. It fails instead of packaging a
stale generated UI.
Note: Claude Desktop currently rejects extra server metadata keys such as package_manager, python_version, and working_dir, so this bundle keeps the uv server block to the manifest fields Claude accepts.
Bundle-specific documentation, runtime settings, and validation steps live in docs/MCPB.md.
The remote server uses session-aware MCP Streamable HTTP and requires an OIDC bearer-token issuer. Session mode enables progress, cancellation, and tools/list_changed notifications; durable long-running work remains Redis-backed. The server refuses to start without this configuration:
$env:MCP_HOST="0.0.0.0"
$env:MCP_PORT="8000"
$env:MCP_HTTP_BASE_URL="https://mcp.example.com"
$env:MCP_HTTP_JWT_ISSUER="https://issuer.example.com"
$env:MCP_HTTP_JWT_AUDIENCE="google-workspace-mcp"
$env:MCP_HTTP_JWKS_URI="https://issuer.example.com/.well-known/jwks.json"
$env:MCP_GOOGLE_OAUTH_REDIRECT_URL="https://mcp.example.com/google/oauth/callback"
$env:MCP_USER_TOKEN_DIR="/srv/mcp-google-workspace/tokens"
$env:MCP_SECRET_FILE="/run/secrets/mcp-google-workspace.json"
uv run python -m mcp_google_workspace.server_httpClients connect with an OIDC bearer JWT. FastMCP validates its issuer, audience, signature, and expiry; the verified iss + sub selects an isolated encrypted Google token. Each user calls connect_google_workspace, opens its returned URL, completes Google consent, and calls refresh_workspace_catalog. The callback is PKCE-protected and one-time; it cannot connect Google credentials to a different MCP principal.
Every GitHub release publishes a signed multi-architecture image for
linux/amd64 and linux/arm64:
docker pull ghcr.io/guinacio/mcp-google-workspace:latest
docker pull ghcr.io/guinacio/mcp-google-workspace:0.3.12The image runs the authenticated Streamable HTTP entrypoint on port 8000. It does not replace the local stdio/MCPB installation. To run it locally:
cp .env.example .env
# Configure the OIDC, Google OAuth redirect, and encryption values in .env.
# Place the Google OAuth client at ./credentials.json.
docker compose up -d
curl http://localhost:8000/health/liveThe Compose service persists encrypted Google tokens and upload metadata in a
named volume. For production, terminate TLS in front of the container, use a
versioned image tag, mount a versioned MCP_SECRET_FILE, and configure the
distributed Redis/S3 contract described under Production operations when
running multiple replicas.
Release images include signed GitHub build provenance. Verify a tag with:
gh attestation verify \
oci://ghcr.io/guinacio/mcp-google-workspace:0.3.12 \
-R guinacio/mcp-google-workspaceGmail (namespaced as gmail_* in composed server):
send_email, reply_email, reply_all_email (true Gmail-thread replies with RFC reply headers)
search_emails (compact metadata-first inbox listing and Gmail query surface)
read_emails (consistent one-to-100 message hydration with selectable detail level)
get_mail_digest, check_mail_updates (unbiased received/sent feeds, including routed and automated mail)
list_labels, create_label, update_label, delete_label, apply_labels
list_attachments, download_attachment
mark_as_read, mark_as_unread, move_email, delete_email
untrash_email, mark_as_spam, mark_as_not_spam
batch_modify, batch_delete
list_filters, create_filter, delete_filter
Drafts: list_drafts, get_draft, create_draft, update_draft, delete_draft, send_draft
Threads: list_threads, get_thread (clean latest message by default), modify_thread, trash_thread, untrash_thread, delete_thread
Forwarding addresses: list_forwarding_addresses, get_forwarding_address, create_forwarding_address, delete_forwarding_address
Vacation settings: get_vacation_settings, update_vacation_settings
Calendar (namespaced as calendar_*):
search_events, read_events, get_calendar_digest, list_calendars, get_calendar_context
check_time_availability, create_event, update_event, respond_to_event, delete_event
Smart scheduling: find_common_free_slots
Event attachments: metadata is included by read_events; mutations use add_event_attachment, remove_event_attachment, download_event_attachment
Event styling + conferencing fields on create/update: color_id, visibility, transparency, conference_data
Conflict prevention: create/update run overlap checks and return status: "CONFLICT" when the slot is unavailable; updates exclude the event being moved
Retry safety: pass a stable idempotency_key to create_event; the App does this automatically and Google Calendar stores a deterministic event ID
Use the availability tool that matches the scheduling intent:
check_time_availability: verify a proposed timeMin/timeMax interval for one or more calendar IDs. Use this when the exact time is already known.
find_common_free_slots: discover candidate intervals across participants inside a broader search window. Use this when the exact meeting time is not known yet.
find_common_free_slots)find_common_free_slots returns candidate meeting slots (not raw FreeBusy output) for all participants in a time window.
Inputs:
participants: list of calendar IDs/emails
time_min, time_max: RFC3339 window
slot_duration_minutes: desired meeting duration
granularity_minutes: candidate step size
max_results: result cap
time_zone: optional timezone used in FreeBusy query
working_hours_start, working_hours_end: optional daily working-hours filter (HH:MM, 24h)
participants must be sent as a native JSON array, for example ["primary", "rodrigo@example.com"]. Use the canonical slot_duration_minutes field.
Working-hours defaults:
working_hours_start: 08:00
working_hours_end: 17:00
Drive (namespaced as drive_*):
Files/content: list_files, get_file, create_folder, create_file_metadata, upload_file
File mutations: update_file_metadata, update_file_content, move_file, copy_file, delete_file
Content retrieval: download_file, export_google_file, get_file_content_capabilities
Sharing: list_permissions, get_permission, create_permission, update_permission, delete_permission
Shared Drives: list_drives, get_drive, hide_drive, unhide_drive
Progress reporting: upload_file, update_file_content, download_file, and export_google_file emit MCP progress updates
Use Drive for file discovery when you need Docs, Sheets, Slides, or Forms file IDs by MIME type or name
Sheets (namespaced as sheets_*):
get_spreadsheet, create_spreadsheet
Values: get_sheet_values, batch_get_sheet_values, append_sheet_values, update_sheet_values
Raw request escape hatch: batch_update_spreadsheet
Docs (namespaced as docs_*):
get_document, create_document
Convenience text mutations: append_document_text, replace_document_text
Raw request escape hatch: batch_update_document
Tasks (namespaced as tasks_*):
Task lists: list_tasklists, get_tasklist, create_tasklist
Tasks: list_tasks, get_task, create_task, update_task, complete_task, move_task, delete_task
People (namespaced as people_*):
Contacts: list_contacts, search_contacts, get_contact, create_contact, update_contact, delete_contact
Contact groups: list_contact_groups, create_contact_group, modify_contact_group_members
Scope note: v1 is personal contacts only; Workspace directory lookup is intentionally excluded
Forms (namespaced as forms_*):
get_form, create_form, batch_update_form
Publishing: set_form_publish_settings
Responses: list_form_responses, get_form_response
Slides (namespaced as slides_*):
get_presentation, create_presentation
Slide reads: get_slide_page, get_slide_thumbnail
Text mutation and raw request escape hatch: replace_text_in_presentation, batch_update_presentation
Apps (namespaced as apps_*, mounted when ENABLE_APPS_DASHBOARD=true):
State/navigation: get_state, set_state, patch_state, today, next_range, prev_range
Dashboard: get_dashboard
Weekly calendar layout: get_weekly_calendar_view (Google Calendar-like week columns)
Detail views: get_event_detail, get_email_detail, get_email_attachment
Calendar mutations are provided only by the core calendar_* tools; the App namespace contains view/state tools only.
Keep (namespaced as keep_*):
create_note, get_note, list_notes, delete_note
share_note, unshare_note
summarize_note (sampling-powered)
compatibility stubs for unsupported Keep v1 operations:
update_note
archive_note, unarchive_note
list_keep_labels, create_keep_label, delete_keep_label
checklist mutation helpers
Note: Keep tools/resources are mounted only when ENABLE_KEEP=true.
Chat (namespaced as chat_*):
list_spaces, get_space
list_messages, get_message
create_message, update_message, delete_message
summarize_space_messages (sampling-powered)
Note: Chat tools/resources are mounted only when ENABLE_CHAT=true.
Meet (namespaced as meet_*, mounted when ENABLE_MEET=true):
Spaces: create_space, get_space, update_space, end_active_conference
Conference records: list_conference_records, get_conference_record
Gemini (namespaced as gemini_*, mounted when ENABLE_GEMINI=true):
generate_image, edit_image
describe_video, analyze_audio
local filesystem or Drive file ID inputs for media tools
generated images are written locally under GEMINI_OUTPUT_DIR
Artifacts and attendance metadata: list_conference_participants, list_conference_recordings, list_conference_transcripts
v1 scope boundary: metadata only; transcript or recording file downloads still belong in Drive if added later
Gmail resources:
gmail://inbox/summary
gmail://labels
gmail://email/{message_id}
Calendar resources:
calendar://today
calendar://week
Drive resources:
drive://recent
drive://shared-drives
drive://file/{file_id}
Keep resources:
keep://notes/recent
keep://note/{note_id}
Chat resources:
chat://spaces
chat://space/{space_id}/messages
chat://space/{space_id}/members
chat://users/{user_ref}
chat://users/me
Apps resources (mounted when ENABLE_APPS_DASHBOARD=true):
apps://dashboard/current
apps://dashboard/day/{ymd}
apps://dashboard/week/{ymd}
apps://calendar/week/{ymd}
Prompts:
compose_email_prompt
reply_email_prompt
summarize_inbox_prompt
summarize_keep_note_prompt
extract_actions_from_keep_notes_prompt
draft_chat_announcement_prompt
summarize_chat_thread_prompt
The remote runtime exposes unauthenticated minimal operational endpoints:
/health/live — event-loop/process liveness
/health/ready — draining, encryption, token storage, Redis, S3, and multi-worker dependency readiness
/version — package/build/MCP protocol versions without secrets
/metrics — Prometheus/OpenTelemetry-compatible low-cardinality metrics
Admission control is principal- and tool-cost-aware:
Variable | Default | Purpose |
|
| Per-principal request rate |
|
| Server-wide active tool calls |
|
| Active calls per principal |
|
| Maximum retained admission-state identities |
|
| Idle admission-state retention |
|
| Gemini/download/export/batch calls |
|
| Standard end-to-end deadline |
|
| Expensive-tool deadline |
|
| In-flight drain interval |
Google provider calls have a failure-window circuit breaker and expose logical-call versus HTTP-attempt metrics so retries are measurable. Logs include hashed principals and correlation IDs, never tokens, message bodies, prompts, filenames, or recipient lists.
For more than one HTTP process/replica, set MCP_WORKERS, MCP_REDIS_URL, MCP_UPLOAD_S3_BUCKET, and configure load-balancer affinity on Mcp-Session-Id; set MCP_SESSION_AFFINITY=true only after that routing is active. Redis then stores encrypted Google credentials, one-time PKCE state, distributed refresh locks, approval tokens, and upload metadata. Set MCP_TOKEN_REDIS_URL only when OAuth state must use a separate Redis deployment. Readiness fails unless OAuth state is Redis-backed and the complete distributed contract is reachable. The HTTP entrypoint uses MCP_REDIS_URL as FASTMCP_DOCKET_URL when the latter is not set. FastMCP native task-enabled tools use the standard MCP task protocol for operation IDs, progress polling, cancellation, expiry, and partial/error results. Additional workers can run with uv run fastmcp tasks worker src/mcp_google_workspace/server.py:workspace_mcp using the same FASTMCP_DOCKET_URL and queue name.
High-impact reversible writes use prepare_workspace_action and commit_workspace_action. The encrypted one-time token is principal-bound, argument-bound, expires after five minutes, and returns an impact preview before commit. Stable resource handles (gdrive:///..., gmail-message:///..., and related schemes) are included where applicable and can be refreshed through resolve_workspace_resource.
Emergency principal invalidation accepts hashed principal storage keys through MCP_REVOKED_PRINCIPALS or the Redis set mcp:revoked_principals. Redis-backed validation fails closed if revocation state cannot be checked.
These features depend on active MCP client support and may be silently unavailable in clients that do not implement the corresponding MCP capabilities.
The composed server exposes files_file_manager, built with FastMCP Prefab and delivered through the standard MCP Apps wire protocol. Its model-visible tool references a generated ui://prefab/tool/.../renderer.html resource served as text/html;profile=mcp-app; the rendered app provides drag-and-drop and native file selection. It is intended for hosted clients such as Claude where a server-local path is not useful and sending binary data through the model context is wasteful.
Typical flow:
Call files_file_manager and let the user choose one or more files (up to 25 MiB each).
Use the opaque upl_... handle returned by the picker as uploaded_file in a Workspace tool. display_name is presentation-only.
The integration reads the bytes directly from scoped server storage; the binary payload does not pass through the model context.
uploaded_file is supported by:
Gmail send_email, create_draft, and update_draft attachments
Drive upload_file and update_file_content
Gemini edit_image, describe_video, and analyze_audio
Local/stdio uploads are session-scoped in memory. A single remote instance can use encrypted filesystem objects plus SQLite metadata through MCP_UPLOAD_DB. Multi-worker production uses Redis metadata and S3-compatible encrypted object storage by configuring MCP_REDIS_URL and MCP_UPLOAD_S3_BUCKET (plus optional MCP_UPLOAD_S3_ENDPOINT and MCP_UPLOAD_S3_PREFIX). Remote files use opaque handles, expire after one hour, and have a 250 MiB per-principal aggregate quota by default. Configure MCP_UPLOAD_TTL_SECONDS and MCP_UPLOAD_QUOTA_BYTES as needed. Uploads are MIME-sniffed, archive expansion is bounded, checksums are verified, and MCP_REQUIRE_MALWARE_SCAN=true enforces ClamAV through MCP_CLAMAV_HOST/MCP_CLAMAV_PORT. Raw host paths are absent from the remote catalog and rejected at runtime.
Use files_delete_file to remove an upload before its TTL expires.
Use files_list_files_page with limit and cursor when a principal has many uploads.
get_mcp_apps_diagnostics reports the UI resource, renderer mode, generated hidden callback addresses, and can run a temporary store/delete self-test with run_self_test=true.
The MCPB manifest forces Prefab's self-contained bundled renderer, avoiding a runtime CDN dependency inside the host iframe.
Requires: an MCP client with MCP Apps/iframe rendering support. Clients without Apps support can still use Google Drive file IDs or trusted local/stdio paths.
Both stdio and authenticated Streamable HTTP use FastMCP's BM25 Tool Search transform by default. The model-visible catalog is reduced to workflow/discovery entry points plus search_tools and call_tool; hidden tools remain callable after discovery. HTTP additionally hides namespaces whose OAuth capability is not granted and removes host-filesystem-only tools and parameters. refresh_workspace_catalog sends tools/list_changed after incremental consent.
Configuration:
MCP_TOOL_SEARCH=auto (default): enable progressive discovery unless MCP_CLIENT_MODEL contains claude.
MCP_TOOL_SEARCH=on: always enable progressive discovery.
MCP_TOOL_SEARCH=off: expose the complete catalog.
MCP_CLIENT_MODEL=claude: disable progressive discovery in auto mode for Claude's current tool/App routing behavior.
The official MCPB manifest declares MCP_CLIENT_MODEL=claude, so Claude Desktop receives the complete catalog. For a manual Claude Desktop stdio configuration, add the same environment variable explicitly.
get_workspace_capabilities reports enabled namespaces, OAuth capability names, and supported file-input strategies. search_workspace searches Drive files, contacts, and Gmail message IDs concurrently and returns normalized references.
connect_google_workspace accepts a capabilities list such as ["drive"], ["gmail", "calendar"], or ["people"]. When omitted it requests Gmail only. Tools build clients with service-specific scopes and return an actionable reconnect error when that capability has not yet been granted. get_google_connection_status accepts an optional capability to verify one grant and reports all currently granted capabilities. Disconnect attempts to revoke the Google grant before deleting encrypted local credentials.
All model-visible tools publish recursively bounded, documented input schemas and closed documented object output schemas. Open input objects are limited to an audited set of genuine Google polymorphic batch maps. List/search responses expose their documented pagination and result-count fields without relying on undeclared conventions. Uncaught tool failures use a machine-readable envelope with code, message, retryable, retry_after, executable required_action, provider_status, and field_errors.
Drive, Calendar, and Gemini Drive-media downloads stream through bounded temporary files instead of buffering complete files in memory. MCP_MAX_DOWNLOAD_BYTES controls the per-download ceiling (default 250 MiB, maximum 10 GiB). Setting MCP_REDIS_URL makes prepare/commit records cross-replica and atomic.
When ENABLE_APPS_DASHBOARD=true, the apps_get_dashboard and apps_get_weekly_calendar_view tools carry an _meta.ui.resourceUri annotation pointing to ui://apps/dashboard-ui. MCP clients that support the Apps rendering protocol (e.g. Claude Desktop) will embed an interactive workspace dashboard UI alongside the tool response.
The UI is a TypeScript web component that communicates with the server via PostMessage. It renders:
A weekly calendar view (all-day events + timed event columns)
An inbox summary with email detail drill-down
Scheduling action buttons (RSVP, reschedule, cancel)
Session-scoped state (current view, anchor date, selected calendars, inbox query) is stored server-side per session and managed through apps_get_state / apps_set_state / apps_patch_state.
Requires: MCP client with App/iframe rendering support.
Long-running tools emit incremental notifications/progress messages via ctx.report_progress(current, total, description). Clients that handle progress notifications can display progress bars or status messages during API-heavy operations.
Tools that emit progress:
Namespace | Tools |
Drive |
|
Apps |
|
Chat |
|
Requires: MCP client that handles notifications/progress.
Optional tools use MCP sampling (ctx.sample()) to generate LLM-powered summaries within the tool response, using the host client's configured model for inference.
Sampling-powered tools:
keep_summarize_note — summarizes a Keep note
chat_summarize_space_messages — summarizes recent messages in a Chat space
Requires: MCP client with sampling/createMessage support (e.g. Claude Desktop). Without sampling support these tools will fail or return an empty summary.
The published JSON Schema is the runtime contract. Send a native JSON object using the documented field names and native arrays/objects. Unknown keys, camelCase aliases, JSON-stringified objects, comma-delimited arrays, and legacy parameter aliases are rejected rather than silently coerced.
Google Keep API v1 currently exposes create, get, list, and delete for notes, plus permission batch create/delete. It does not expose a direct update/patch endpoint, archive/unarchive endpoints, or dedicated label endpoints in v1. The MCP server returns explicit unsupported responses for those operations.
This repo includes:
.claude-plugin/marketplace.json
.claude-plugin/plugin.json
and a compatibility manifest at:
plugins/google-workspace/.claude-plugin/plugin.json
Reference docs:
From within Claude Code:
/plugin marketplace add guinacio/mcp-google-workspace
/plugin install google-workspace@google-workspace-mcpLocal checkout flow (from this repository root):
/plugin marketplace add .
/plugin install google-workspace@google-workspace-mcpOptional refresh after updates:
/plugin marketplace update google-workspace-mcpmcpServers)If you want to run it directly in Claude Desktop without marketplace install, add this to your Claude Desktop config JSON under mcpServers.
Windows config file:
%APPDATA%\Claude\claude_desktop_config.json
macOS config file:
~/Library/Application Support/Claude/claude_desktop_config.json
Linux config file:
~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"google-workspace": {
"command": "uv",
"args": [
"run",
"--directory",
"c:/path/to/mcp-google-workspace",
"python",
"-m",
"mcp_google_workspace"
],
"env": {
"ENABLE_APPS_DASHBOARD": "true",
"ENABLE_KEEP": "false",
"ENABLE_CHAT": "false",
"ENABLE_MEET": "false"
}
}
}
}Replace c:/path/to/mcp-google-workspace with your local repo path.
uv run pytest -qApps smoke test:
# in-process mode (auto-enables apps namespace)
uv run python scripts/qa_apps_smoke.py
# or against a running Streamable HTTP server
uv run python scripts/qa_apps_smoke.py --http-url http://127.0.0.1:8001/mcpCall a tool by name with the given arguments.
Use this to execute tools discovered via search_tools.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the tool to call | |
| arguments | No | Arguments to pass to the tool |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It accurately describes the function (calling a tool with arguments) but does not disclose any behavioral traits such as side effects, authentication needs, or error handling. For a meta-tool, this is adequate but not exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, each serving a purpose: stating the action and providing usage context. There is no wasted text, and it is well front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with full schema coverage and no output schema, the description covers the essential purpose and usage context. It could mention that the tool returns the called tool's output, but this is not critical for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds minimal new meaning beyond stating 'with the given arguments'. The baseline score of 3 is appropriate as the schema already documents both parameters well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Call a tool by name with the given arguments' and provides context by tying it to tools discovered via search_tools. It distinguishes its purpose from sibling tools, which are specific file or workspace operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence explicitly advises to use this tool for executing tools found via search_tools. This gives clear when-to-use guidance, though it does not explicitly mention when not to use it or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Atomically consume a prepared action token and execute its exact bound arguments.
| Name | Required | Description | Default |
|---|---|---|---|
| commit_token | Yes | One-time, principal-bound token from prepare_workspace_action's response; expires 5 minutes after issuance and is consumed on first use. |
| Name | Required | Description |
|---|---|---|
| tool | No | Response field: tool. |
| error | No | Error message or structured error details when the call failed. |
| result | No | Response field: result. |
| status | No | Machine-readable operation status. |
| context | No | Identifying request arguments echoed back with an error. |
| resource | No | Stable cross-tool Workspace resource handle when applicable. |
| provider_status | No | HTTP status code returned by the Google API for a failed call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses atomic token consumption and execution of exact bound arguments, which adds behavioral context beyond the annotations (readOnlyHint=false, idempotentHint=false). It clarifies that the operation is one-time and the action is predetermined, complementing the annotation hints. There is no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, terse sentence that immediately conveys the core action. It has no redundant phrases and every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is part of a two-phase workflow (prepare/commit), and the description does not explicitly situate it in that workflow. The parameter description and sibling list provide context, and the presence of annotations and output schema mitigates the need for further details, but the description alone is minimal and leaves workflow ordering implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage for the single parameter with a detailed description of the token's lifecycle. The main description only refers to it as a 'prepared action token' and mentions 'exact bound arguments', which adds minimal semantic value beyond the schema. Baseline is 3 due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'consume' and 'execute' with a clear resource ('prepared action token' and 'exact bound arguments'). It distinctly describes the atomic consumption and execution, and differentiates this tool from its siblings, especially prepare_workspace_action, by focusing on the commit step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage after preparation by referring to a 'prepared action token', but it does not explicitly state when to use it or provide exclusions. The parameter description in the schema gives additional context about the token's origin and expiry, but the main description lacks a direct 'use after prepare_workspace_action' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Connect locally with loopback OAuth or return a remote incremental-consent URL.
| Name | Required | Description | Default |
|---|---|---|---|
| capabilities | No | Google Workspace capability names to request scopes for, e.g. ['calendar', 'chat', 'docs', 'drive', 'forms', 'gmail', 'keep', 'meet', 'people', 'sheets', 'slides', 'tasks']; defaults to ['gmail'] when omitted. |
| Name | Required | Description |
|---|---|---|
| mode | No | Response field: mode. |
| state | No | Response field: state. |
| action | No | Response field: action. |
| resource | No | Stable cross-tool Workspace resource handle when applicable. |
| connected | No | Response field: connected. |
| expires_at | No | Response field: expires at. |
| capabilities | No | Response field: capabilities. |
| after_consent | No | Response field: after consent. |
| granted_scopes | No | Response field: granted scopes. |
| requested_scopes | No | Response field: requested scopes. |
| authorization_url | No | Response field: authorization url. |
| granted_capabilities | No | Response field: granted capabilities. |
| newly_requested_scopes | No | Response field: newly requested scopes. |
| requested_capabilities | No | Response field: requested capabilities. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and openWorldHint=true, meaning the tool modifies state and may have unknown side effects. The description discloses two OAuth modes but does not elaborate on side effects, credential storage, or the OAuth flow. It adds context beyond annotations but still leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the two modes of operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and annotations are present, the description covers the key behavioral modes. However, it lacks details on prerequisites (e.g., existing Google credentials), error conditions, and behavior when already connected. Still fairly complete for a connection tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the tool description does not add additional meaning to the single parameter 'capabilities' beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'connect' and the resource 'Google Workspace' via OAuth, and distinguishes two modes: local loopback OAuth and remote incremental-consent URL. This differentiates it from siblings like 'disconnect_google_workspace' and 'get_google_connection_status'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to connect to Google Workspace) but does not explicitly state when not to use or mention alternatives like 'refresh_workspace_catalog'. It provides clear context but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove only the authenticated user's encrypted Google OAuth credentials.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | Whether to enable confirm. |
| Name | Required | Description |
|---|---|---|
| action | No | Response field: action. |
| status | No | Machine-readable operation status. |
| resource | No | Stable cross-tool Workspace resource handle when applicable. |
| grant_revoked | No | Response field: grant revoked. |
| revocation_error | No | Response field: revocation error. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description states 'Remove' which implies destructive action, but annotations set destructiveHint=false. Additionally, description restricts to 'only the authenticated user's' credentials (scoped), while annotations set openWorldHint=true, suggesting broader effects. This direct contradiction warrants a score of 1.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with precise, front-loaded information. No unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool that removes credentials, the description lacks context on side effects, reversibility, or output. Even with output schema present (not shown), the brevity leaves agents underinformed about the operation's impact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single boolean parameter 'confirm'. The description adds no additional meaning beyond the schema, achieving baseline score for well-covered schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'remove' and the resource 'authenticated user's encrypted Google OAuth credentials', distinguishing it from sibling tools like connect_google_workspace or get_google_connection_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or context. It only states what it does without directing agent decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload and manage files. Drop files here to send them to the server.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| view | Yes | Declarative picker UI tree. |
| state | Yes | Initial picker UI state. |
| $prefab | Yes | Prefab protocol metadata. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description claims 'Upload and manage files', implying write operations, but annotations have readOnlyHint=true, which indicates a read-only tool. This is a clear contradiction. No additional behavioral context is provided beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise (two sentences) but lacks essential details and is front-loaded with the purpose. However, it is too vague and does not earn its place due to missing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and no parameters, the description is contradictory to annotations and fails to explain how the tool works or what its behavior is. It is not complete enough for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, and the description does not explain how to specify files for upload (e.g., via drag-and-drop). The phrase 'Drop files here' is insufficient for an AI agent to understand the mechanism.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description says 'Upload and manage files' which indicates a broad file management purpose, but 'manage' is vague and does not clearly distinguish from sibling tools like files_list_files which handle specific list operations. The purpose is somewhat clear but lacks specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as files_list_files. The description does not provide context for appropriate usage or mention any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all uploaded files with metadata.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes | Files stored in the current user session. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that files are listed with metadata, but doesn't disclose behavior like ordering or bulk retrieval limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise at 5 words, with no wasted content. Every word is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description covers the main function. However, it could mention that results are not paginated (given the sibling 'files_list_files_page').
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, schema coverage is 100%. The description implies no filtering by stating 'all uploaded files', which adds sufficient meaning beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists uploaded files with metadata, using a specific verb and resource. However, it does not differentiate from the sibling 'files_list_files_page' which likely provides paginated results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool versus alternatives like 'files_list_files_page' or 'files_file_manager'. There is no context for choosing this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Page through uploaded files without returning an unbounded catalog.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of uploaded files to return (1-100). | |
| cursor | No | Opaque continuation cursor returned by the previous page. |
| Name | Required | Description |
|---|---|---|
| count | Yes | Number of files returned in this page. |
| files | Yes | Uploaded file summaries in this page. |
| next_cursor | No | Cursor for the next page, or null at the end. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds minimal behavioral context beyond 'page through' and avoiding unbounded results, but does not explain pagination mechanics (e.g., cursor usage) in detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the verb and resource, containing zero wasted words. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and clear parameter descriptions, the description is mostly adequate. However, it does not mention that the response includes a cursor for subsequent pages, which would be helpful context for a pagination tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with both 'limit' and 'cursor' having clear descriptions. The tool description adds no additional meaning beyond what the schema provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('page through') and resource ('uploaded files'), and distinguishes it from an unbounded catalog, which contrasts with the likely non-paginated sibling tool 'files_list_files'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you need pagination to avoid an unbounded catalog, but it does not explicitly mention when to use this tool versus the sibling 'files_list_files' or provide any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report whether the authenticated MCP user has connected Google Workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| capability | No | Single capability name to check granted scopes for, e.g. 'gmail' or 'calendar'; omit to report overall connection state without a per-capability scope check. |
| Name | Required | Description |
|---|---|---|
| state | No | Response field: state. |
| action | No | Response field: action. |
| resource | No | Stable cross-tool Workspace resource handle when applicable. |
| connected | No | Response field: connected. |
| expires_at | No | Response field: expires at. |
| principal_key | No | Response field: principal key. |
| granted_scopes | No | Response field: granted scopes. |
| required_scopes | No | Response field: required scopes. |
| checked_capability | No | Response field: checked capability. |
| granted_capabilities | No | Response field: granted capabilities. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds no behavioral details beyond what annotations provide, missing an opportunity to explain scope or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. However, it could be slightly more informative without breaking conciseness, e.g., mentioning the output format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, presence of an output schema, and rich annotations, the description is adequate. No major gaps, though it could mention that it returns boolean or status details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the single optional parameter 'capability' is fully described in the schema). The tool description does not add any parameter-specific meaning, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Report' and resource 'whether... connected Google Workspace'. Distinguishes from siblings like `connect_google_workspace` and `disconnect_google_workspace` which perform actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like `get_workspace_capabilities` or `search_workspace`. The description is too minimal to provide usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe the file-picker MCP Apps contract and optionally verify callbacks.
| Name | Required | Description | Default |
|---|---|---|---|
| run_self_test | No | Whether to enable run self test. |
| Name | Required | Description |
|---|---|---|
| status | Yes | Machine-readable diagnostic status. |
| self_test | Yes | Optional store/delete callback self-test result. |
| picker_tool | Yes | Model-visible tool that opens the file picker. |
| apps_enabled | Yes | Whether the file-picker Apps provider is mounted. |
| resource_uri | Yes | MCP Apps UI resource URI advertised by the picker. |
| renderer_mode | Yes | Prefab renderer delivery mode. |
| max_file_bytes | Yes | Maximum decoded size accepted for one picker upload. |
| hidden_callbacks | Yes | App-callable backend tool addresses hidden from the model catalog. |
| resource_mime_type | Yes | MIME type served for the UI resource. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, establishing a safe read profile. The description adds the optional verification behavior via run_self_test, which complements the annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is front-loaded with the primary action, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description need not detail return values. However, it lacks context about what the 'file-picker MCP Apps contract' entails and what the verification involves, leaving some uncertainty.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description covers 100% of the single parameter. The description adds no additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to describe the file-picker MCP Apps contract and optionally verify callbacks. The verb 'describe' and specific resource distinguish it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidelines on when to use this tool versus alternatives. The unique functionality implies when it's appropriate, but the description lacks explicit usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe available namespaces, consent capabilities, and file-transfer choices.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| status | No | Machine-readable operation status. |
| resource | No | Stable cross-tool Workspace resource handle when applicable. |
| discovery | No | Response field: discovery. |
| file_inputs | No | Response field: file inputs. |
| enabled_namespaces | No | Response field: enabled namespaces. |
| oauth_capabilities | No | Response field: oauth capabilities. |
| optional_namespaces | No | Response field: optional namespaces. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide strong safety signals (readOnlyHint=true, destructiveHint=false, idempotentHint=true), so the description needs less behavioral disclosure. The description adds context about the content (namespaces, consent capabilities, file-transfer choices) but does not elaborate on broader behavior like openWorldHint implications or whether results are cached. Since annotations already communicate the safe, read-only nature, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly states the tool's purpose without fluff or redundancy. Every word earns its place, making it highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters, a safe read-only annotation set, and an output schema present, the tool's description covers the necessary context well. The description outlines the three main output domains (namespaces, consent, file-transfer), which is sufficient guidance. Slightly more context about the tool's role in the overall workspace workflow could elevate it, but it is generally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
This tool takes zero parameters, so the schema is trivially complete. The description compensates by enriching what the agent should expect in the output (namespaces, consent, file-transfer), which provides semantic value beyond the empty schema. A baseline of 4 for zero params is justified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Describe') and identifies a distinct resource ('workspace capabilities' including namespaces, consent capabilities, and file-transfer choices). It clearly distinguishes the tool's broad informational scope from sibling tools like get_google_connection_status or refresh_workspace_catalog, though it doesn't explicitly name a differentiating sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the go-to tool for exploring workspace capabilities, which is a natural fit given sibling tools like connect_google_workspace or prepare_workspace_action. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention prerequisites like requiring an active connection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Preview and bind one consequential action to a short-lived one-time commit token.
| Name | Required | Description | Default |
|---|---|---|---|
| arguments | Yes | Exact keyword arguments to bind and later execute unchanged for tool_name. | |
| tool_name | Yes | Full name of the consequential tool to prepare; must be one of ['calendar_update_event', 'drive_create_permission', 'gmail_batch_modify', 'gmail_send_email', 'sheets_batch_update_spreadsheet']. Other tools do not use the prepare/commit protocol. |
| Name | Required | Description |
|---|---|---|
| error | No | Error message or structured error details when the call failed. |
| impact | No | Response field: impact. |
| status | No | Machine-readable operation status. |
| context | No | Identifying request arguments echoed back with an error. |
| resource | No | Stable cross-tool Workspace resource handle when applicable. |
| expires_at | No | Response field: expires at. |
| next_action | No | Response field: next action. |
| commit_token | No | Response field: commit token. |
| provider_status | No | HTTP status code returned by the Google API for a failed call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only, open-world, non-idempotent behavior; the description adds value by noting the token is 'short-lived one-time' and that the action is 'consequential.' However, it does not disclose what 'preview' entails, token expiration mechanics, or potential side effects beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It conveys the core purpose and key behavioral characteristic ('short-lived one-time commit token') efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's role in a prepare/commit protocol, the description is complete enough to understand the basic function, but it omits mention of the companion 'commit_workspace_action' or any follow-up step. The output schema and annotations cover some context, but the protocol dependency is not explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents both parameters with 100% coverage, including the enum list for 'tool_name' and a clear description for 'arguments.' The description adds no additional parameter details, so it does not exceed the baseline set by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: 'Preview and bind one consequential action to a short-lived one-time commit token.' It uses specific verbs ('preview', 'bind') and identifies the resource (action, token), effectively distinguishing it from the sibling 'commit_workspace_action' by emphasizing the binding step rather than execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used as a preparatory step for a consequential action, but it does not explicitly state when to use it versus alternatives like 'commit_workspace_action' or 'call_tool.' There is no direct mention of a workflow or conditions that should trigger its use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Refresh capability-aware tools after Google consent or disconnection.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| status | No | Machine-readable operation status. |
| resource | No | Stable cross-tool Workspace resource handle when applicable. |
| notification_sent | No | Response field: notification sent. |
| granted_capabilities | No | Response field: granted capabilities. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and openWorldHint=true, so the description adds value by explaining the 'refresh' behavior and the trigger events. However, it doesn't detail what the refresh entails (e.g., updating tool definitions, clearing caches) or potential side effects, leaving some ambiguity despite annotations providing baseline context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the action and resource. Every word is necessary, and there is no fluff. It efficiently conveys the purpose and trigger.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema exists, the description is largely complete. It clearly identifies the trigger context (consent/disconnection) and the action (refresh), which is sufficient for an agent to decide when to invoke it. Minor improvement could mention that the tool is typically used after workspace connection changes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters with 100% schema coverage. According to the rubric, baseline is 4 for 0 parameters. The description doesn't need to add parameter semantics since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: refreshing capability-aware tools triggered by Google consent or disconnection. It uses a specific verb (Refresh) and resource (capability-aware tools), and distinguishes itself from sibling tools like connect_google_workspace and disconnect_google_workspace by specifying the trigger events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use the tool: after Google consent or disconnection. This provides clear context, though it doesn't explicitly mention when not to use it or name alternatives. However, the trigger events naturally guide the agent to appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a stable Workspace URI to fresh compact metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| uri | Yes | Stable Workspace resource URI previously returned in a tool response's 'resource' field. |
| Name | Required | Description |
|---|---|---|
| status | No | Machine-readable operation status. |
| resource | No | Response field: resource. |
| next_actions | No | Response field: next actions. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so safety and side-effect profile is already provided. The description's word 'fresh' implies dynamic data, but it does not disclose any additional behavioral traits such as authentication needs, rate limits, or external calls. With annotations covering the basics, this is adequate but not enriched, scoring 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 10 words, front-loaded with the core action and result. Every word earns its place, with no filler or repetition. This is exemplary conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter, a rich schema description, and an output schema, the description is mostly complete. It clearly conveys the tool's purpose and the schema explains the input. The only minor gap is that the description doesn't explicitly mention any preconditions like the URI belonging to the current workspace or that fresh metadata may require network access, but the output schema and annotations fill most needs. A 4 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description for the 'uri' parameter is already detailed, explaining it is a 'Stable Workspace resource URI previously returned in a tool response's resource field,' providing full meaning. The main description adds no parameter-specific information, and schema coverage is 100%, so the baseline of 3 applies. No extra credit is warranted for the description itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Resolve') and resource ('a stable Workspace URI') with an outcome ('fresh compact metadata'). This is distinct from sibling tools like search_workspace or refresh_workspace_catalog, which involve different operations. It fully explains what the tool does in one concise sentence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The schema parameter description adds context that the URI is 'previously returned in a tool response's resource field,' which strongly implies when to use this tool (when you have a resource URI from a prior call). However, the main description does not explicitly state alternatives or when not to use the tool, lacking direct comparison to search_workspace or refresh_workspace_catalog. Clear context with no exclusions justifies a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for tools using natural language.
Returns matching tool definitions ranked by relevance, in the same format as list_tools.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural language query to search for tools |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It states the output format matches list_tools (implying a read operation), but does not mention any side effects, required permissions, or performance characteristics. Basic transparency is present but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences with no filler. The first sentence states the core purpose, and the second clarifies the output format. Every word contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema is present, the description does not need to detail return values. However, it omits information about result limits, sorting, or pagination. For a simple search tool with one parameter, completeness is nearly adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description for the 'query' parameter already says 'Natural language query to search for tools'. The tool description adds no further semantics beyond what the schema provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Search for tools using natural language' and specifies it returns matching tool definitions ranked by relevance, identical to list_tools. This clearly identifies the verb, resource, and output format, distinguishing it from sibling tools like 'search_workspace'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for searching tools but provides no explicit guidance on when to use it versus alternatives, nor does it mention when not to use it. The agent must infer usage from the name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Drive files, contacts, and Gmail IDs through one normalized entry point.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search or filter expression used to narrow the results. | |
| services | No | Subset of services to search: any of 'drive', 'people', 'gmail'; omit to search all three. | |
| max_results_per_service | No | Maximum results per service to include in the result. |
| Name | Required | Description |
|---|---|---|
| count | No | Number of items in this response. |
| query | No | Response field: query. |
| errors | No | Response field: errors. |
| status | No | Machine-readable operation status. |
| matches | No | Response field: matches. |
| has_more | No | Whether another page is available. |
| resource | No | Stable cross-tool Workspace resource handle when applicable. |
| services | No | Response field: services. |
| fetched_at | No | RFC3339 time when this response was fetched. |
| next_page_token | No | Opaque token for the next page, or null. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare safe, read-only, idempotent behavior. The description adds no additional behavioral context (e.g., query syntax, result aggregation, or rate limits), missing an opportunity to add value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundancy. Every word contributes to the purpose, achieving maximum conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of a full output schema and rich annotations, the description is minimally adequate. However, it lacks contextual details such as expected result structure or query format nuances, leaving some information gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all three parameters. The description does not add parameter-specific details beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search' and identifies the resources (Drive files, contacts, Gmail IDs) through a unified entry point. It does not explicitly differentiate from sibling tools but provides a clear purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a cross-service search use case but does not provide explicit guidance on when to use this tool versus alternatives like search_tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.3.10commit_workspace_action3 fields changedOutput schema / properties / contextAdded value: +{
+ "description": "Identifying request arguments echoed back with an error.",
+ "type": "object"
+}Output schema / properties / errorAdded value: +{
+ "description": "Error message or structured error details when the call failed.",
+ "type": [
+ "object",
+ "string"
+ ]
+}Output schema / properties / provider_statusAdded value: +{
+ "description": "HTTP status code returned by the Google API for a failed call.",
+ "type": "integer"
+}get_workspace_capabilities6 fields changedOutput schema / properties / optional_namespaces / properties / apps / itemsRemoved value: -{}Output schema / properties / optional_namespaces / properties / apps / typePrevious value: -"array"New value: +"boolean"Output schema / properties / optional_namespaces / properties / chat / typeAdded value: +"boolean"Output schema / properties / optional_namespaces / properties / gemini / typeAdded value: +"boolean"Output schema / properties / optional_namespaces / properties / keep / typeAdded value: +"boolean"Output schema / properties / optional_namespaces / properties / meet / typeAdded value: +"boolean"prepare_workspace_action3 fields changedOutput schema / properties / contextAdded value: +{
+ "description": "Identifying request arguments echoed back with an error.",
+ "type": "object"
+}Output schema / properties / errorAdded value: +{
+ "description": "Error message or structured error details when the call failed.",
+ "type": [
+ "object",
+ "string"
+ ]
+}Output schema / properties / provider_statusAdded value: +{
+ "description": "HTTP status code returned by the Google API for a failed call.",
+ "type": "integer"
+}resolve_workspace_resource1 field changedOutput schema / properties / resource / typeAdded value: +"object"v0.3.7call_toolcommit_workspace_actionconnect_google_workspacedisconnect_google_workspacefiles_file_managerfiles_list_filesfiles_list_files_pageget_google_connection_statusget_mcp_apps_diagnosticsget_workspace_capabilitiesprepare_workspace_actionrefresh_workspace_catalogresolve_workspace_resourcesearch_toolssearch_workspaceMost tools have distinct purposes, but the file tools overlap: files_list_files and files_list_files_page both list files, and files_file_manager is a catch-all that could confuse selection. The meta-tools call_tool and search_tools also add ambiguity about when to use direct vs meta tools.
Naming is mostly verb_noun with underscores, but there are inconsistencies: some tools use google_workspace, others just workspace, and the files_ prefix is applied inconsistently (files_file_manager is a noun phrase, not a verb). The files_list_files_page variant deviates from the simple verb_noun pattern.
15 tools is within the expected range, but the set includes redundant file listing tools and generic meta-tools (call_tool, search_tools) that could be considered unnecessary. Still, the count is reasonable for the scope.
The tool surface lacks common Google Workspace operations like sending email, creating events, or reading contacts beyond search. It focuses on connection management, search, and a generic action mechanism, leaving significant gaps for an agent trying to perform typical Workspace tasks.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
The Google Compute Engine MCP server is a fully-managed Model Context Protocol server that provides tools to manage Google Compute Engine resources through AI agents. It enables capabilities including instance management (creating, starting, stopping, resetting, listing), disk management, handling instance templates and group managers, viewing machine and accelerator types, managing images, and accessing reservation and commitment information. The server operates as a zero-deployment, enterprise-grade endpoint at https://compute.googleapis.com/mcp with built-in IAM-based security.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
AI-powered medical document management for cancer patients. Google Drive, Gmail, Calendar via MCP.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/guinacio/mcp-google-workspace'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
