Google Workspace MCP Server
Provides tools for reading and managing Google Calendar events, including listing calendars, viewing schedules, finding free slots, creating, moving, modifying, and deleting events with safety constraints.
Click on "Deploy 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., "@Google Workspace MCP Server What's on my calendar today?"
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.
Google Workspace MCP Server
A hardened, safety-first Google Calendar Model Context Protocol (MCP) server designed for enterprise reliability, strict data isolation, and deep agentic workflow integrations. This server empowers AI agents (like Claude Desktop, Cursor, or Antigravity) to read and manage calendars while enforcing strict user-defined security limits at runtime.
โจ Core Features & Safety Constraints
To protect user accounts and prevent unauthorized modifications, the server implements multiple runtime safeguards:
๐ Domain Boundary Whitelist: Blocks agents from sending calendar invites to external or unauthorized email domains (via
GWS_ALLOWED_DOMAINS).๐ก๏ธ PII & Description Scrubber: Redacts email addresses, phone numbers, and meeting details dynamically based on privacy levels (
GWS_PII_MODE).๐ฅ Double-Booking Prevention: Checks calendar availability automatically before booking an event unless the client explicitly requests an override (
ignore_availability=True).โ ๏ธ Two-Turn Delete Flow: Forces a dry-run confirmation step for event deletions, returning a detailed preview card before executing changes.
๐ Profile-Based Token Storage: Isolates authentication tokens based on
GWS_PROFILEto allow multi-tenant/account setups (e.g., separating personal and corporate accounts).โฑ๏ธ API Rate Limiter: Enforces a global minimum interval of 100ms between calls to avoid flooding Google Cloud API quotas.
๐ Structured Audit Logging: Appends timestamped, owner-only readable (
chmod 600) JSON log lines for all modifying actions.
Related MCP server: gcal-mcp
๐ Quick Start & Installation
1. Run the Interactive Installer (Recommended)
We provide an interactive installer script that handles virtual environments, fetches dependencies, guides you through placing your Google credentials, runs the auth flow, and auto-injects configuration settings into Claude Desktop:
# Clone the repository and kick off the configuration engine
curl -fsSL https://raw.githubusercontent.com/wrik0/gws-workspace-agent/master/setup.sh | bashAlternatively, if you already cloned the repository locally:
./setup.shYou can also configure a custom profile (e.g., work) during setup:
./setup.sh --profile work2. Manual Installation
If you prefer to configure the environment manually:
# Clone the repository
git clone https://github.com/wrik0/gws-workspace-agent.git
cd gws-workspace-agent
# Set up environment and install package in editable mode
uv venv
uv pip install -e ".[dev]"3. Google OAuth Setup
Before running the server, place your Google Cloud Client Secrets file (credentials.json) in the standard application data folder:
Linux:
~/.config/google-workspace-mcp/credentials.jsonmacOS:
~/Library/Application Support/google-workspace-mcp/credentials.jsonWindows:
%APPDATA%\gws\google-workspace-mcp\credentials.json
Next, run the CLI authorization utility:
# Performs browser login and caches the OAuth token
# On Unix (using the symlinked binary):
gws-auth
# Or directly via virtual environment:
.venv/bin/gws-authโ๏ธ Environment Configuration
You can configure the server behaviour using environment variables or equivalent command-line options when serving:
Environment Variable | CLI Option | Default | Description |
|
|
| Workspace profile name. Resolves to |
|
|
| Mode of operation: |
|
|
| Privacy filter: |
|
| None | Comma-separated domain whitelist for invitees (e.g. |
| None | System Local | Local timezone database name (e.g. |
| None |
| Destination path for the append-only JSON audit logs. |
๐ Command Line Interface (CLI)
The package exposes three entry points:
gws-serve
Starts the stdio FastMCP server.
gws-serve --mode readonly --pii-mode redact --allowed-domains company.comgws-auth
Starts the OAuth token refresh browser loop.
# Request only read-only scopes from Google
gws-auth --mode readonly
# Request write scopes (requires verification if app is in sandbox)
gws-auth --mode fullgws-purge
Purges cached tokens and credentials files.
# Deletes cached token file but leaves credentials.json intact
gws-purge --token-only
# Deletes the entire application config directory
gws-purge --all๐ Client Integration
Claude Desktop
Add this to your claude_desktop_config.json:
{
"mcpServers": {
"google-workspace": {
"command": "~/.local/bin/gws-serve",
"args": ["--readonly", "--pii-mode", "redact"],
"env": {
"GWS_ALLOWED_DOMAINS": "mycompany.com"
}
}
}
}Cursor IDE
Navigate to Cursor Settings > Features > MCP > + Add New MCP Server:
Name:
google-workspaceType:
commandCommand:
~/.local/bin/gws-serve --readonly --pii-mode redact
๐ฆ MCP Tools Reference
Read Tools (Available in readonly and full modes)
list_calendars(): Lists all calendars in the account with their name, ID, and access roles (e.g. owner, reader).view_schedule(time_min, time_max, calendar_id="primary"): Displays events in a specific window. Outputs summary, times, descriptions, and color emojis (derived from Google Color IDs).find_slots(time_min, time_max, duration_minutes, calendar_id="primary"): Queries free/busy state and aggregates open slots available for scheduling.
Write Tools (Available only in full mode)
create_event(summary, start_iso, end_iso, ...): Creates a calendar event. Validates invitee domains, checks double-booking conflicts, and records the action inaudit.log.move_event(event_id, new_start_iso, new_end_iso): Shift events in time via a singlePATCHAPI request.modify_event(event_id, ...): Dynamically updates text details or appends new whitelisted attendees.delete_event(event_id, confirm=False): Two-turn deletion flow. Run withconfirm=Falseto inspect the event details card, and run withconfirm=Trueto execute the API call.
๐งช Developer & Testing Suite
We use pytest for unit testing. The test suite uses mocks to fully simulate Google Cloud services and config directories:
# Run pytest locally
.venv/bin/pytest -vStyle & Format Enforcement
To maintain code quality, run Ruff checkers:
# Format codebase
.venv/bin/ruff format
# Run linter checks
.venv/bin/ruff check --fix๐ License
This project is licensed under the terms of the MIT license.
Available Tools
7 toolscreate_eventA
Create a new calendar event. Returns event ID and HTML link.
Use ignore_availability=True only when the user explicitly requests overlapping/conflicting bookings.
Inputs: end_iso (required), summary (required), start_iso (required), color_id, +6 more. Returns: result
delete_eventADestructive
Delete a calendar event by its ID.
ALWAYS call twice:
delete_event(confirm=False) -> Returns preview card.
delete_event(confirm=True) -> Executes deletion.
Inputs: event_id (required), confirm, calendar_id. Returns: result
find_slotsARead-only
Find open time slots using the Google freebusy API.
Checks availability for the user AND all invitees in one API call. Returns available windows (not raw busy blocks) โ agent-ready output.
Inputs: time_max (required), time_min (required), duration_minutes (required), calendar_ids, +1 more. Returns: result
list_calendarsARead-only
List all calendars accessible to the user.
Returns calendar IDs needed for multi-calendar operations. Call once per session and reuse the IDs.
Inputs: no named parameters. Returns: result
modify_eventB
Modify text/metadata fields of an event using PATCH.
Inputs: event_id (required), calendar_id, new_summary, new_color_id, +3 more. Returns: result
move_eventC
Change the start and end time of an existing event by ID.
Inputs: event_id (required), new_end_iso (required), new_start_iso (required), calendar_id. Returns: result
view_scheduleARead-only
List calendar events in a time range with color-coded type labels.
Window is capped at GWS_MAX_WINDOW_DAYS to prevent bulk data exposure. Returns events formatted with emoji type labels derived from color IDs.
Inputs: time_max (required), time_min (required), calendar_id, max_results. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 7 tools
Each tool has a clearly distinct purpose: creating, deleting, modifying, moving events, finding slots, listing calendars, and viewing schedule. No overlap in functionality.
All tools follow a consistent verb_noun pattern in snake_case (e.g., create_event, delete_event, find_slots). Perfect alignment.
7 tools cover the essential calendar operations without bloat. Each tool serves a clear need, making the set well-scoped.
Core CRUD and scheduling workflows are supported, but a dedicated tool for retrieving a single event by ID or managing attendees is missing, which agents might need in some scenarios.
Maintenance
Related MCP Connectors
Hosted Google Calendar MCP server for AI agents. No self-hosting or Google Cloud setup.
Calendar API for AI agents: events, availability, Google/Microsoft setup, scheduling, and iCal.
Secure Linux sandboxes for AI agents, as MCP tools.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceMCP server that lets AI agents manage Google Calendar -- create events, check availability, and manage schedules.MIT
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server for read-only Google Calendar integration, providing calendar access to AI assistants.-
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI assistants to manage Google Calendar events, calendars, sharing, and scheduling with full read/write access across multiple Google accounts, supporting natural language creation, recurring events, and Google Meet.40 npmMIT
- AlicenseNot gradedqualityDmaintenanceA production-ready MCP server that lets AI assistants interact with your personal Google Calendar using the Google Calendar API and OAuth 2.0.79 npmMIT