Which integrations are available for this server?

Enables non-destructive Gmail/Google Workspace email search and retrieval over IMAP, plus email sending through SMTP. Integrates with Google Workspace calendars via CalDAV, allowing calendar discovery and listing, creating, and deleting calendar events.

How do I use Google Workspace Hybrid MCP Server?

This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.

Google Workspace Hybrid MCP Server

by hemelbesem90s

Overview Schema Source Related Servers Discussions Admin

Python

Local

Google Workspace Hybrid MCP Server

Python 3.10+ License: MIT Code style: ruff Type Checked: mypy

High-performance, vendor-neutral Model Context Protocol (MCP) server for Google Workspace. It combines non-destructive IMAP email inspection and CalDAV multi-calendar querying with native operating system biometric gates (Touch ID on macOS and Windows Hello on Windows).

Architecture Overview

The system separates the low-level MCP communication engine from higher-level agent reasoning:

┌────────────────────────────────────────────────────────┐
│   Agentic AI Client (Antigravity / Claude / Cursor)    │
└───────────────────────────┬────────────────────────────┘
                            │
               Stdio MCP Protocol (JSON-RPC)
                            │
┌───────────────────────────▼────────────────────────────┐
│          Google Workspace Hybrid MCP Server            │
│  (Neutral Protocol Engine, Zero-Password Keychain)    │
├───────────────────────────┬────────────────────────────┤
│     Read Operations       │      Write Operations      │
│  • IMAP PEEK (BODY.PEEK)  │  • SMTP SSL Email Dispatch │
│  • CalDAV Multi-Calendar  │  • CalDAV Event Creation   │
│  • Zero state mutation    │  • CalDAV Event Deletion   │
│  • No read status changes │  • Biometric Presence Gate │
└─────────────┬─────────────┴─────────────┬──────────────┘
              │                           │
              │         Hardware Prompt   │
              │    (Touch ID / Windows Hello)
              ▼                           ▼
┌───────────────────────────┐ ┌──────────────────────────┐
│ Google Workspace Endpoints│ │ Native Hardware Security │
│ • imap.gmail.com:993      │ │ • macOS LAContext        │
│ • smtp.gmail.com:465      │ │ • Windows Hello          │
│ • calendar.google.com/dav │ │ • LocalAuthentication    │
└───────────────────────────┘ └──────────────────────────┘

Core Security Principles

Zero-Password Leakage: Credentials load securely from the OS Keychain or environment variables. Passwords never appear in logs, error payloads, or tool schemas.
Non-Destructive Reads (BODY.PEEK[]): IMAP queries always use BODY.PEEK[]. Reading or searching emails never marks them as seen or read on the server.
Hardware Biometric Presence Gate: All state mutations (send_email, create_calendar_event, delete_calendar_event) require explicit user confirmation (confirm=true) and trigger a native hardware biometric prompt before connecting.
RFC 4791 CalDAV Multi-Calendar Architecture: Automatically discovers primary and secondary calendars (such as client or organization calendars). Queries use standard WebDAV REPORT XML with VCALENDAR/VEVENT filtering.

Related MCP server: mail-calendar-mcp

Separation of Concerns: Agentic Skills vs. MCP Core

This MCP server acts as a strictly neutral and generic execution engine. It contains no hardcoded user identities, email addresses, personal signatures, or proprietary customer business logic.

To achieve tailored workflows, agents use a local agentic skill (such as gmail-reader-searcher or calendar-reader-searcher) on top of this server:

Responsibility	MCP Server Core (`workspace-mcp`)	Local Agentic Skill (Workspace Layer)
Data Access	Connects to IMAP, SMTP, and CalDAV	Prompts the user and interprets queries
Credential Storage	Resolves credentials from OS Keychain	Refers to configured account profile
Safety Gate	Enforces Touch ID / Windows Hello presence	Obtains user intent and parameters
Email Templates	Generic MIME constructor	Domain-specific Dutch/English wording
Signatures & Brand	Neutral sender formatting	Specific company branding and disclaimers
Client Code Lookups	None (parameter-agnostic)	Project ID mapping (UPID/CID routing)

Available MCP Tools

The server registers 8 tools across diagnostics, email, and calendar management:

Tool Name	Type	Biometric Gate	Description
`check_connection_status`	Read	No	Tests IMAP, SMTP, and CalDAV credentials and connection health.
`search_emails`	Read	No	Searches inbox by query, subject, sender, or unread status (`BODY.PEEK[]`).
`get_email`	Read	No	Retrieves full email metadata, body, and attachments by ID.
`send_email`	Write	Yes	Sends email via SMTP SSL. Requires `confirm=true` and Touch ID.
`list_calendars`	Read	No	Discovers accessible primary, secondary, and team calendars.
`list_calendar_events`	Read	No	Queries calendar events with text search and calendar filtering.
`create_calendar_event`	Write	Yes	Creates a new calendar event. Requires `confirm=true` and Touch ID.
`delete_calendar_event`	Write	Yes	Deletes a calendar event by UID. Requires `confirm=true` and Touch ID.

Configuration & Environment Variables

The server resolves credentials in the following order:

Environment variables.
Configuration file path (WORKSPACE_CONFIG_PATH or config.json).
OS Keychain (macOS Keychain service grobler_gmail or custom service name).

Environment Variables

Variable	Default	Purpose
`WORKSPACE_EMAIL`	(None)	Workspace email address.
`WORKSPACE_APP_PASSWORD`	(None)	App-specific password for IMAP/SMTP/CalDAV.
`WORKSPACE_SENDER_NAME`	(None)	Display name for outgoing emails.
`WORKSPACE_KEYRING_SERVICE`	`grobler_gmail`	OS Keychain service name.
`WORKSPACE_IMAP_SERVER`	`imap.gmail.com`	IMAP server hostname.
`WORKSPACE_IMAP_PORT`	`993`	IMAP SSL port.
`WORKSPACE_SMTP_SERVER`	`smtp.gmail.com`	SMTP server hostname.
`WORKSPACE_SMTP_PORT`	`465`	SMTP SSL port.
`WORKSPACE_CALDAV_URL`	`https://calendar.google.com/calendar/dav/{email}/`	CalDAV discovery URL.
`WORKSPACE_MCP_ENABLE_WRITE_TOOLS`	`true`	Set to `false` to disable all write operations.
`WORKSPACE_MCP_REQUIRE_BIOMETRIC`	`true`	Set to `false` in automated CI/CD environments.
`WORKSPACE_MCP_LOG_LEVEL`	`INFO`	Server logging level.

Installation & Setup

1. Requirements

Python 3.10+ (Python 3.13 recommended)
macOS (Touch ID) or Windows (Windows Hello)
Google account with an App Password configured

2. Virtual Environment Setup

# Clone the repository
git clone https://github.com/hemelbesem90s/Google-Workspace-MCP.git
cd Google-Workspace-MCP

# Create virtual environment and install dependencies
uv venv --python 3.13
source .venv/bin/activate
uv pip install -e ".[dev]"

3. Store Credentials in OS Keychain

You can store your App Password in the macOS Keychain without touching plain-text files:

# Store email and app password
python3 -c "import keyring; keyring.set_password('grobler_gmail', 'email', 'user@example.com')"
python3 -c "import keyring; keyring.set_password('grobler_gmail', 'app_password', 'xxxx-xxxx-xxxx-xxxx')"

4. Verify Connection

workspace-mcp --test-connection

MCP Registration

Add the server to your MCP configuration file (e.g. ~/.gemini/config/mcp_config.json or Claude Desktop config):

{
  "mcpServers": {
    "google-workspace": {
      "command": "/absolute/path/to/Google-Workspace-MCP/.venv/bin/workspace-mcp",
      "args": [],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
        "WORKSPACE_MCP_ENABLE_WRITE_TOOLS": "true",
        "WORKSPACE_MCP_REQUIRE_BIOMETRIC": "true",
        "WORKSPACE_MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Development & Verification

Run the full verification suite using make:

make check      # Runs linter (ruff), type checker (mypy), and test suite (pytest)
make test       # Runs pytest with coverage (must pass >= 85%)
make lint       # Runs ruff code formatting checks
make typecheck  # Runs mypy static type analysis
make schemas    # Regenerates lazy MCP tool schemas

License

This project is licensed under the MIT License.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Mailbox MCP
com.mailbox-mcp
Read, send, file and search email in any Gmail, Microsoft 365 or IMAP mailbox, plus its calendar.
Email Calendar Management
2
https://mcp.mailbox-mcp.com/db/mcp
mail
com.anymailmcp
Read, send, organize, watch email on any IMAP mailbox: Gmail, iCloud, OVH, Zoho, Fastmail + CalDAV.
Email Calendar Management
1
https://anymailmcp.com/mcp
Mailbox MCPA
com.mailbox-mcp.mcp
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
Calendar Management Communication Email
431
https://mcp.mailbox-mcp.com/db/mcp
muse.space
space.muse
Let your agent into iCloud Mail, calendar and contacts. It gets actions, never your password.
Email Calendar Management Workplace & Productivity
1
https://muse.space/mcp

Related MCP Servers

imap-mcp
Email Communication
agimenezdev
A
license
Not graded
quality
D
maintenance
Enables email management via IMAP and SMTP with multi-account support, safe sending with confirmation, and read-only modes.
Updated 5 months ago (2026-06-17 18:25 UTC)
MIT
mail-calendar-mcp
Email Calendar Management
mathewcsims
F
license
A
quality
D
maintenance
Enables full read/write control over Apple Mail.app and Calendar.app on macOS, exposing all configured accounts without per-provider setup.
Updated 4 months ago (2026-07-23 06:00 UTC)
51
1
-
Apple Mail MCP
Email Communication
jenyago
A
license
A
quality
B
maintenance
Enables searching and reading email across permitted accounts and mailboxes on macOS, plus optionally saving drafts for review, without sending or deleting messages.
Updated 4 days ago (2026-11-03 17:56 UTC)
5
MIT
Airmail MCP
Email Calendar Management Workplace & Productivity
AvaTar-ArTs
A
license
Not graded
quality
C
maintenance
Enables AI clients to read, search, compose, organize, and act on emails, plus manage calendars, contacts, reminders, folders, rules, signatures, aliases, and account preferences through a local bridge.
Updated 11 days ago (2026-10-27 23:41 UTC)
48 npm
MIT

Google Workspace Hybrid MCP Server

Architecture Overview

Core Security Principles

Separation of Concerns: Agentic Skills vs. MCP Core

Available MCP Tools

Configuration & Environment Variables

Environment Variables

Installation & Setup

1. Requirements

2. Virtual Environment Setup

3. Store Credentials in OS Keychain

4. Verify Connection

MCP Registration

Development & Verification

License

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

imap-mcp

mail-calendar-mcp

Apple Mail MCP

Airmail MCP