Gmail Tools & Resources

Relevant source files

The following files were used as context for generating this wiki page:

• packages/google-workspace-mcp/src/google_workspace_mcp/services/gmail.py
• packages/google-workspace-mcp/src/google_workspace_mcp/tools/gmail.py
• packages/google-workspace-mcp/src/google_workspace_mcp/resources/gmail.py
• packages/google-workspace-mcp/README.md
• tests/google-workspace-mcp/unit/tools/gmail/test_draft_tools.py

Introduction

The Gmail Tools & Resources module within the google-workspace-mcp package provides a standardized interface for AI models to interact with the Gmail API via the Model Context Protocol (MCP). It enables comprehensive email management capabilities, including querying messages, managing drafts, and handling attachments, all while abstracting the underlying complexity of Google's API calls and authentication.

This module acts as a bridge between the MCP Hub and the GmailService, exposing discrete "tools" for actions and "resources" for stateful data access. These capabilities allow AI assistants to perform complex workflows such as responding to threads, bulk deleting messages, or retrieving unread counts within a secure, governed environment.

Sources: packages/google-workspace-mcp/README.md:12-25, packages/google-workspace-mcp/src/google_workspace_mcp/tools/gmail.py:1-12

Architecture and Data Flow

The Gmail integration follows a tiered architecture:

1. MCP Layer: Defines tools and resources using the @mcp decorator. These functions handle input validation and route requests to the service layer.
2. Service Layer (GmailService): Extends BaseGoogleService to perform the actual interaction with the Google Gmail API v1. It handles pagination, MIME encoding/decoding, and error translation.
3. Data Models: Internal functions like _parse_message and _extract_body convert raw API JSON payloads into structured dictionaries suitable for AI context.

Tool Execution Flow

The following diagram illustrates the flow from a tool call to the Google API:

Gmail Tools

Tools represent callable actions that an AI model can execute. Each tool is registered with a name and a description that helps the model understand when to use it.

Messaging Tools

Tool Name	Parameters	Description
query_gmail_emails	query (str), max_results (int)	Searches emails using standard Gmail syntax (e.g., "is:unread").
gmail_get_message_details	email_id (str)	Retrieves a complete message, including headers and snippet.
gmail_send_email	to (list[str]), subject (str), body (str), cc, bcc	Composes and sends an email directly.
gmail_reply_to_email	email_id (str), reply_body (str), send (bool), reply_all (bool)	Creates a reply to a thread; defaults to saving as a draft.
gmail_bulk_delete_messages	message_ids (list[str])	Deletes multiple emails in a single batch operation.

Sources: packages/google-workspace-mcp/src/google_workspace_mcp/tools/gmail.py:15-240

Draft Management

Draft operations allow for a "human-in-the-loop" workflow where the AI prepares content for user review.

Gmail Resources

Resources provide static or dynamic state information from Gmail, mapped to custom URIs.

• gmail://labels: Returns a list of all user-defined and system labels. Derived from the labels().list() API endpoint.
• gmail://unread_count: Provides the count of unread emails in the inbox using the resultSizeEstimate from a query for is:unread in:inbox.

Sources: packages/google-workspace-mcp/src/google_workspace_mcp/resources/gmail.py:15-55, packages/google-workspace-mcp/src/google_workspace_mcp/services/gmail.py:532-555

Implementation Details

Message Parsing and Body Extraction

The GmailService includes robust logic for handling multipart MIME messages. It recursively searches through message parts to find text/plain content and decodes it from URL-safe Base64.

# From packages/google-workspace-mcp/src/google_workspace_mcp/services/gmail.py
def _extract_body(self, payload: dict[str, Any]) -> str | None:
    if payload.get("mimeType") == "text/plain":
        data = payload.get("body", {}).get("data")
        if data:
            return base64.urlsafe_b64decode(data).decode("utf-8")
    # ... handles multipart/ recursively

Sources: packages/google-workspace-mcp/src/google_workspace_mcp/services/gmail.py:476-508

Error Handling

Errors from the Google API are caught by the service layer and passed to handle_api_error. The tools then inspect these results; if an error dictionary is detected, they raise a ValueError with a descriptive message to inform the AI model of the failure.

Sources: packages/google-workspace-mcp/src/google_workspace_mcp/tools/gmail.py:75-85, packages/google-workspace-mcp/src/google_workspace_mcp/services/gmail.py:20-25

Conclusion

The Gmail Tools & Resources module provides a high-level, AI-friendly interface for the Google Gmail service. By combining specific tools for email lifecycle management with resources for account status, it enables complex automated messaging workflows while maintaining the security and structure required by the Model Context Protocol.