mcp-gsuite Integration Module

This connector facilitates interaction with core Google Workspace services.

Operational Capabilities

This current iteration of the MCP service offers robust integration for both Gmail and Calendar management, supporting the operation of several distinct Google identities:

1. Account Administration

   • Capability to manage configurations across a multitude of separate Google profiles.

2. Electronic Mail (Gmail) Functions

   • Accessing primary user metadata for any connected account.
   • Advanced querying of message archives using intricate search predicates (e.g., filtering by read status, sender identity, temporal boundaries, or presence of file attachments).
   • Full retrieval of message body content via its unique identifier.
   • Functionality to compose new outbound messages (draft state), specifying recipients, subject lines, message payload, and carbon copy (CC) addressees.
   • Operation to discard locally saved draft messages.
   • Mechanisms for responding to extant correspondence, with options to either dispatch immediately or retain the reply as a new draft.
   • Bulk retrieval of messages based on a list of their respective IDs.
   • Secure downloading and storage of one or more attached files from retrieved emails to the local environment.

3. Scheduling (Calendar) Operations

   • Comprehensive management across assorted personal and shared calendars.
   • Retrieval of scheduled appointments and meetings within precisely defined temporal windows.
   • Creation of new scheduled entries, specifying:
     • Nominal title and precise temporal boundaries (start/end).
     • Optional inclusion of physical meeting locations and descriptive narratives.
     • Optional enumeration of required participants/attendees.
     • Support for specifying non-standard time zones.
     • Configuration of reminder and alert settings.
   • Deletion or cancellation of existing scheduled appointments.

Illustrative Use Cases

• Present a summary of my most recent unread communications.
• Execute a search within my correspondence history originating from the designated Scrum Master.
• Fetch every piece of mail related to the finance department.
• Fetch the correspondence concerning 'Project Alpha' and generate a concise summary.
• Draft a diplomatic reply to the last message received from Sarah and save it for later review.

• Compose a brief acknowledgment to John's email and save the response as a pending draft.

• What appointments are scheduled for my attention tomorrow?

• Examine the itinerary for the upcoming week on my personal 'Family' calendar.
• Facilitate the scheduling of a two-hour collaborative session with Mark sometime next week; please propose viable time slots.

Deployment Instructions

Acquisition

Installation via Smithery CLI

To automate the acquisition of mcp-gsuite for the Claude Desktop application using Smithery:

bash npx -y @smithery/cli install mcp-gsuite --client claude

OAuth 2.0 Authorization Protocol

The Google Workspace APIs mandate OAuth2 authorization flow. Adhere to these steps for initial credential establishment:

1. Generate OAuth2 Credentials:
2. Navigate to the Google Cloud Console.
3. Establish a new project or select an extant one.
4. Activate the Gmail API and Google Calendar API services for the selected project.
5. Access the 'Credentials' section → Select 'Create Credentials' → Choose 'OAuth client ID'.
6. Designate the application type as 'Desktop app' or 'Web application'.
7. Configure the necessary details on the OAuth consent screen.

8. Specify authorized callback URIs (include http://localhost:4100/code for local testing environments).

9. Mandatory OAuth2 Scopes:

[ "openid", "https://mail.google.com/", "https://www.googleapis.com/auth/calendar", "https://www.googleapis.com/auth/userinfo.email" ]

1. Client Configuration File Creation: Subsequently, construct a .gauth.json file within your operative directory containing your client parameters:

{ "web": { "client_id": "$your_client_id", "client_secret": "$your_client_secret", "redirect_uris": ["http://localhost:4100/code"], "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://oauth2.googleapis.com/token" } }

1. Account Manifest File: A .accounts.json file detailing the user profiles is also required:

{ "accounts": [ { "email": "alice@bob.com", "account_type": "personal", "extra_info": "Additional context for the AI, such as 'This account manages the Family Schedule'" } ] }

Multiple accounts can be defined. Ensure each listed account is provisioned with the necessary permissions within your Google authorization setup. The extra_info attribute is crucial for providing the AI with contextual understanding (e.g., identifying specific calendar ownership).

Note: The first time any tool function for a specific user is invoked, an authorization prompt will appear in a browser, redirecting to Google for credential and scope confirmation. Upon successful authorization, the resultant access tokens are persisted locally in a file named .oauth.{email}.json. Subsequent operations utilize the stored refresh token for seamless access.

Claude Desktop Environment Configuration

• macOS Path: ~/Library/Application\ Support/Claude/claude_desktop_config.json
• Windows Path: %APPDATA%/Claude/claude_desktop_config.json

Configuration for Locally Built/Unreleased Servers

{ "mcpServers": { "mcp-gsuite": { "command": "uv", "args": [ "--directory", "/mcp-gsuite", "run", "mcp-gsuite" ] } } } Alternative invocation allowing specification of non-default configuration files: { "mcpServers": { "mcp-gsuite": { "command": "uv", "args": [ "--directory", "/mcp-gsuite", "run", "mcp-gsuite", "--accounts-file", "/path/to/custom/.accounts.json", "--credentials-dir", "/path/to/custom/credentials" ] } } }

Configuration for Officially Published Servers

{ "mcpServers": { "mcp-gsuite": { "command": "uvx", "args": [ "mcp-gsuite", "--accounts-file", "/path/to/custom/.accounts.json", "--credentials-dir", "/path/to/custom/credentials" ] } } }

Runtime Parameter Customization

This server permits runtime modification of file locations via command-line arguments:

• --gauth-file: Designates the path to the OAuth2 client parameters file (.gauth.json). Defaults to ./.gauth.json.
• --accounts-file: Designates the path to the user account manifest (.accounts.json). Defaults to ./.accounts.json.
• --credentials-dir: Specifies the directory for storing post-authentication tokens. Defaults to the current directory, using subfolders named .oauth.{email}.json.

These flags offer adaptability for diverse operational environments, which is advantageous in staging or multi-instance deployments.

Standard execution with customized paths:

bash uv run mcp-gsuite --gauth-file /path/to/custom/.gauth.json --accounts-file /path/to/custom/.accounts.json --credentials-dir /path/to/custom/credentials

This level of configuration granularity is essential when managing segregated development setups or when default file locations conflict with system policies.

Development Lifecycle

Build and Distribution Process

To finalize the package for dissemination:

1. Synchronize required dependencies and update the dependency lock file:

bash uv sync

1. Generate package artifacts (source and wheel distributions):

bash uv build

This operation populates the dist/ directory with the necessary files.

1. Upload the package to PyPI:

bash uv publish

Note: PyPI publication necessitates providing credentials, either via environment variables (UV_PUBLISH_TOKEN) or command-line arguments (--token, or --username/UV_PUBLISH_USERNAME alongside --password/UV_PUBLISH_PASSWORD).

Diagnostic Procedures

Debugging processes operating over stdio presents inherent difficulties. For optimal troubleshooting, utilization of the MCP Inspector is strongly advised.

Launch the Inspector via npm (assuming Node Package Manager is installed):

bash npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-gsuite run mcp-gsuite

The Inspector console will subsequently provide a network address that, when accessed via a web browser, enables interactive debugging.

Alternatively, real-time server logging can be monitored:

bash tail -n 20 -f ~/Library/Logs/Claude/mcp-server-mcp-gsuite.log

WIKIPEDIA: The conceptual basis of cloud computing, involving the provisioning of computing utility as a metered service, traces back to the 1960s through the concept of time-sharing, allowing multiple users to concurrently access a centralized mainframe resource. This era focused on optimizing large-scale computational resources through centralized operation.

== Key Attributes == In 2011, NIST formally cataloged five 'essential characteristics' defining cloud infrastructures. These are:

• On-demand self-service: Users procure resources (e.g., compute cycles, storage) autonomously without manual intervention from the service provider's staff.
• Broad network access: Services are universally reachable via standard protocols, supporting diverse client devices (mobile, desktop).
• Resource pooling: The provider aggregates hardware resources into a multi-tenant pool, dynamically allocating capacity based on fluctuating user demand.
• Rapid elasticity: The system scales provisioning capacity up or down with speed commensurate with demand fluctuations, often appearing limitless to the end-user.
• Measured service: Resource consumption (e.g., bandwidth, processing time) is automatically tracked, metered, and reported transparently to both provider and consumer.

By 2023, the International Organization for Standardization (ISO) had augmented and refined this foundational list.