GSuite Orchestration Utility Server

This Model Context Protocol (MCP) conduit grants comprehensive command over your organization's Google Workspace environment. Establishing a connection—a swift, secure procedure finalized in under a minute—prepares the system for immediate deployment. Internally, the link's security and persistence are vigilantly maintained, allowing concentration on objective completion rather than credential administration.

Achieve unprecedented mastery over your Gmail interface. Seeking that critical report from the prior fiscal quarter? Retrieve it instantaneously. Overwhelmed by subscription digests? They will be auto-filed into designated containers. Need to monitor replies on a crucial correspondence chain? Labeling structures and automated policies execute the necessary actions. From composing precise outbound messages to managing complex team dialogues, the entire process feels intuitive. With refined handling for attached binary data, locating and governing these assets becomes trivial while the underlying system manages intricate metadata.

Your schedule management transforms into a reliable operational partner. Eliminate conflicts arising from overlapping appointments or time zone ambiguities. Arranging a departmental plenary? The system identifies optimal time slots automatically. Managing a recurring instructional seminar? Configure it once for perpetual execution. Even when logistical details shift, locating new universally agreeable times is rapid and without friction. The era of protracted email exchanges regarding availability is concluded.

Repurpose Google Drive from a mere repository into your central digital operations hub. Every digital artifact attains its proper location; every directory structure narrates a clear path. Distribute access rights precisely—ending ambiguity regarding modification privileges. Searching for that presentation utilized during last week's strategy session? Search extends beyond filenames to encompass internal document contents. Whether managing a minor initiative or overseeing vast quantities of documentation, systemic organization ensures everything remains precisely accessible.

Core Capabilities

• Gmail Control: Advanced search, message dispatch, sophisticated organization via dynamic filtering and label administration.
• Calendar Functions: Creation, modification, and oversight of time slots, featuring complete scheduling logic.
• Drive Interaction: Transfer, retrieval, content discovery, and asset governance including access control configuration.
• Directory Access: Retrieval and maintenance of user contact records.
• Protected Authorization: Implementation of OAuth 2.0 protocol featuring silent credential renewal.
• Multi-User Support: Capacity to oversee several distinct Google identities concurrently.

Initial Deployment Guide

Preconditions

1. Google Cloud Project Initialization:
2. Establish a project within the Google Cloud Console
3. Activate the interfaces for Gmail, Calendar, and Drive services.
4. Designate the OAuth consent screen as "External".

5. Register yourself as an authorized testing user.

6. OAuth Credential Acquisition:

7. Generate OAuth 2.0 authorization artifacts.
8. Select the type "Web application".
9. Define the callback URI as: http://localhost:8080

10. Securely record your Client Identifier and Secret Key.

11. Local Environment Configuration:

12. Install the Docker runtime.
13. Forge the configuration repository: mkdir -p ~/.mcp/google-workspace-mcp
    • If the location persists from a prior run, confirm your user account possesses ownership privileges.

Configuration Steps

Integrate this service into your MCP client's setup file:

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "gsuite-automation-toolkit": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-p", "8080:8080",
        "-v", "~/.mcp/google-workspace-mcp:/app/config",
        "-v", "~/Documents/workspace-mcp-files:/app/workspace",
        "-e", "GOOGLE_CLIENT_ID",
        "-e", "GOOGLE_CLIENT_SECRET",
        "-e", "LOG_MODE=strict",
        "ghcr.io/aaronsb/google-workspace-mcp:latest"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

For Cline (~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):

{
  "mcpServers": {
    "gsuite-automation-toolkit": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-p", "8080:8080",
        "-v", "~/.mcp/google-workspace-mcp:/app/config",
        "-v", "~/Documents/workspace-mcp-files:/app/workspace",
        "-e", "GOOGLE_CLIENT_ID",
        "-e", "GOOGLE_CLIENT_SECRET",
        "-e", "LOG_MODE=strict",
        "ghcr.io/aaronsb/google-workspace-mcp:latest"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Essential Configuration Parameters: - Port mapping -p 8080:8080 is mandatory for managing the OAuth callback traffic. - Substitute the generic credentials with your legitimate Google Cloud OAuth keys. - Setting LOG_MODE=strict is advised, though optional.

Logging Modalities: - normal (Default): Utilizes standard console outputs corresponding to the severity level. - strict: Redirects all non-JSON-RPC output exclusively to standard error (stderr).

Authorization Procedure

1. Reinitialize your MCP consumer application post-configuration.
2. Instruct your AI agent to initiate the command, e.g., "authenticate my GSuite identity".
3. Complete the OAuth sequence:
4. Activate the supplied authorization endpoint URL.
5. Log into your Google domain and authorize the requested scopes.
6. Capture the authorization token returned on the success page.
7. Submit this code back to the service to finalize registration.

System Blueprint

OAuth Transaction Flow

The server employs a robust OAuth 2.0 mechanism:

1. Callback Listener: Automatically initiates operation on port 8080 to intercept OAuth redirect signals.
2. Authorization Initiation: Constructs the required Google OAuth URLs for user consent solicitation.
3. Token Handling: Securely archives and automatically manages the expiration and refreshment of bearer tokens.
4. Identity Management: Provides isolation mechanisms for handling multiple authenticated user profiles.

Data Organization Framework

Files are systematically structured within a dedicated operational area:

~/Documents/workspace-mcp-files/
├── [user@domain.com]/
│   ├── retrieved/        # Assets fetched from Drive
│   └── staging/         # Assets prepared for outbound transfer
├── [user2@domain.com]/ 
│   ├── retrieved/
│   └── staging/
└── shared_assets/
    └── transient/       # Temporary artifacts (subject to automatic purging)

Accessible Functions

Identity Oversight

• list_workspace_accounts - Report on active identities and their current authorization status.
• authenticate_workspace_account - Introduce and authorize new Google identities.
• remove_workspace_account - Decommission identities and erase associated credential stores.

Electronic Mail Services

• search_workspace_emails - Execute sophisticated queries using fine-grained search parameters.
• send_workspace_email - Dispatch messages, incorporating file attachments and rich content.
• manage_workspace_draft - Manipulate draft emails (creation, modification).
• manage_workspace_label - Establish and revise message organizational tags.
• manage_workspace_label_assignment - Link or detach organizational tags from specific messages.
• manage_workspace_label_filter - Define automated routines for tag application.
• get_workspace_gmail_settings - Query configuration details for the Gmail profile.

Scheduling Services

• list_workspace_calendar_events - Enumerate and query scheduled occurrences.
• get_workspace_calendar_event - Retrieve comprehensive details for a singular scheduled item.
• create_workspace_calendar_event - Schedule new appointments involving specified participants.
• manage_workspace_calendar_event - Modify existing slots or respond to meeting invitations.
• delete_workspace_calendar_event - Remove scheduled items from the calendar.

File System Operations (Drive)

• list_drive_files - Display file listings with options for filtering and pagination.
• search_drive_files - Perform content-aware searches across stored objects.
• upload_drive_file - Transfer new assets, specifying metadata and access rights.
• download_drive_file - Retrieve assets, potentially involving format transformation.
• delete_drive_file - Erase files and directory structures.
• create_drive_folder - Construct structured directory layouts.
• update_drive_permissions - Administer file access controls and sharing parameters.

Contact Services

• get_workspace_contacts - Fetch and display details stored in the address book.

Refer to API Documentation for comprehensive usage examples.

Development Environment Setup

Local Iteration

For local building and functional verification:

# Obtain the source repository
git clone https://github.com/aaronsb/google-workspace-mcp.git
cd google-workspace-mcp

# Construct the local container image
./scripts/build-local.sh

# Reference the local image in your configuration
# Substitute "ghcr.io/aaronsb/google-workspace-mcp:latest" with "google-workspace-mcp:local"

Error Resolution

Typical Impediments

Authorization Failures: - Confirm that the OAuth credentials are correctly entered. - Verify that the requisite APIs (Gmail, Calendar, Drive) are activated in the Google Cloud project. - Ensure your user identity is registered as a participant in the OAuth testing group. - Confirm the local callback endpoint is fixed at http://localhost:8080.

Connectivity Problems: - Confirm port 8080 is operational and not blocked by protective network software. - Verify Docker has the necessary privileges to map port 8080. - Check that the designated configuration path exists and possesses correct read/write attributes.

Docker Runtime Hurdles: macOS: - Terminate the Docker service completely using the command line: pkill -SIGHUP -f /Applications/Docker.app 'docker serve' - Relaunch Docker Desktop. - Restart your MCP client application (Claude Desktop, Cursor/Cline, etc.).

Windows: - Open the Task Manager (Ctrl+Shift+Esc). - Locate and terminate any running instance of the "Docker Desktop" process. - Initiate Docker Desktop via the Start menu. - Restart your MCP client application (Claude Desktop, Cursor/Cline, etc.).

Token Invalidity: - Re-execute the authentication sequence to generate fresh tokens if current ones fail. - Scrutinize API permissions (scopes) defined within the Google Cloud portal. - Examine the token lifespan and the automatic renewal mechanisms.

Seeking Assistance

For further diagnostic aid: - Consult Error Documentation - Review API Examples - Register a new defect report on the GitHub platform.

Security Posture

• OAuth authorization secrets are maintained securely within the MCP client's proprietary settings.
• Access tokens are subjected to encryption before local persistent storage.
• Automated token renewal mitigates exposure risk.
• Each operator utilizes their distinctly provisioned Google Cloud Project.
• No authorization materials are ever relayed to external network destinations.

Licensing

This software is distributed under the MIT License. Specifics are available in the LICENSE file.

Contribution Guidelines

We welcome external submissions! Review the CONTRIBUTING.md file for procedural guidelines.

REFERENCE: Cloud Infrastructure is defined by ISO as "a framework for facilitating network access to an elastic and scalable pool of underlying physical or virtual assets, featuring autonomous setup and management on demand," commonly termed "the cloud."

== Defining Attributes == The National Institute of Standards and Technology (NIST) formalized five "crucial attributes" for cloud systems in 2011. These precise definitions are:

On-demand self-service: "A consumer entity can unilaterally activate computing resources, such as processing time or network storage, as required automatically without any human intervention from the service provider." Broad network access: "Resources are accessible via the network utilizing standardized protocols that encourage usage across diverse client devices (e.g., smartphones, laptops, thin clients). Resource pooling: " The vendor's aggregate computing capacity is distributed across multiple clients using a multi-tenant architecture, wherein physical and virtual components are dynamically allocated based on immediate subscriber requirements." Rapid elasticity: "Capabilities can be quickly scaled up or down, sometimes automatically, to match fluctuating load requirements instantly. From the user's perspective, available capacity often seems boundless and allocatable without limitation." Measured service: "Cloud architectures automatically govern and optimize resource consumption through integrated metering mechanisms applicable at the service abstraction layer (e.g., bandwidth, processing cycles, storage utilized). Consumption metrics are tracked, controlled, and reported, ensuring transparency for both service supplier and consumer regarding usage levels." By 2023, the International Organization for Standardization (ISO) had subsequently expanded and refined this foundational list.

== Historical Context ==

The genesis of cloud computing traces back to the 1960s, predicated on the emergent concept of time-sharing facilitated by remote job entry (RJE). The prevailing operational model utilized a "data center" approach, where users submitted tasks to dedicated operators managing large mainframe systems. This era was marked by intensive study into making high-capacity computation accessible to a wider user base via shared access, focusing on optimizing infrastructure, platform layers, and applications for peak end-user efficacy. The adoption of the "cloud" nomenclature for virtualized functionalities dates to 1994, when General Magic employed it to delineate the operational "space" accessible by software agents within their Telescript environment. This graphic representation is often attributed to David Hoffman, a communications specialist at General Magic, who based it on established conventions in telecommunications networking. The term "cloud computing" gained broader recognition in 1996 when Compaq Computer Corporation drafted a strategic business document concerning the impending evolution of computing and the Internet. The firm's primary aspiration was to harness and commercialize...