MCP Connector for Google Workspace Services

This server module enables programmatic access to Google productivity suites.

Operational Capabilities

Currently, this connector offers deep integration with Gmail and Google Calendar, supporting the following feature sets:

1. General Account Handling

2. Support for managing credentials across several distinct Google identities.

3. Gmail Functions

4. Fetching details about the authenticated Gmail user.
5. Advanced querying of messages based on custom criteria (e.g., sender, date span, unread status, presence of attachments).
6. Retrieval of the full content of a message given its unique identifier.
7. Composition of new draft messages, specifying recipients, subject line, body text, and carbon copy (CC) addressees.
8. Removal/destruction of existing draft messages.
9. Functionality to send replies to inbound messages, with an option to dispatch immediately or persist as a draft.
10. Bulk retrieval of multiple messages based on a list of their IDs.

11. Securely saving several email attachments to the local filesystem.

12. Calendar Management

13. Ability to oversee and manage multiple associated calendars.
14. Retrieval of scheduled appointments within defined temporal boundaries.
15. Event creation, configurable with:
    • Event title and precise start/finish timestamps.
    • Optional inclusion of a venue/location and detailed description.
    • Optional invitation of other participants.
    • Support for non-standard time zones.
    • Configuration of proactive notification settings.
16. Removal/cancellation of existing scheduled appointments.

Illustrative Usage Scenarios

Here are examples of queries this connector can process:

• "Show me my most recent unread correspondence."
• "Scan for messages originating from the designated Scrum Master."
• "Fetch every piece of mail sent by the accounting department."
• "Locate the message concerning 'ABC' and provide a synopsis."
• "Draft a courteous reply to the last message from Alice and save it as a pending item."

• "Reply to Bob's email with a brief acknowledgement. Keep it in drafts."

• "What items are scheduled on my itinerary for the following day?"

• "Review the events next week on my personal 'Family' schedule."
• "I need to organize a two-hour meeting with Tim sometime next week. Propose suitable time slots."

Initial Setup Guide (Quickstart)

Installation

Automated Deployment via Smithery

Install the G Suite Integration module for your client environment automatically using the Smithery utility:

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

OAuth 2.0 Authorization Flow

Interaction with Google Workspace APIs necessitates secure OAuth2 authentication. Please follow these precise configuration steps:

1. Generate OAuth2 Credentials:
2. Navigate to the Google Cloud Console.
3. Establish a new project or select an existing one.
4. Activate both the Gmail API and the Google Calendar API within your project settings.
5. Access the "Credentials" section, then select "Create Credentials" -> "OAuth client ID".
6. Designate the application type as either "Desktop app" or "Web application".
7. Configure the necessary details on the OAuth consent screen.

8. Crucially, define authorized redirect URIs, ensuring inclusion of http://localhost:4100/code for local development testing.

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 (.gauth.json): Create this file in your operational directory, populating it with your client credentials:

{ "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 Mapping File (.accounts.json): This file details the specific Google accounts the system will interface with:

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

Multiple accounts can be listed. Ensure each listed account has granted the necessary permissions in your Google Auth application. The extra_info field is vital for providing contextual knowledge to the AI regarding the specific contents or purpose of that account.

Authorization Step: Upon the initial execution of any tool command targeting a specific account, a web browser window will launch, directing you to Google for consent regarding credentials and requested scopes. Upon successful authorization, the resulting access tokens are stored locally in a file named .oauth.{email}.json. Future operations will utilize the persistent refresh token.

Desktop Client Configuration Locations

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

Configuration for Locally Developed/Unreleased Servers

{ "mcpServers": { "mcp-gsuite": { "command": "uv", "args": [ "--directory", "/mcp-gsuite", "run", "mcp-gsuite" ] } } }

Configuration for Officially Published Servers

{ "mcpServers": { "mcp-gsuite": { "command": "uvx", "args": [ "mcp-gsuite" ] } } }

Runtime Configuration Parameters

The server permits customization of file locations via command-line arguments at execution time:

• --gauth-file: Defines the filepath for the OAuth2 client configuration (.gauth.json). Defaults to the current directory's ./.gauth.json.
• --accounts-file: Specifies the path to the user account mapping file (.accounts.json). Defaults to ./.accounts.json.
• --credentials-dir: Sets the storage location for acquired OAuth tokens. By default, tokens are kept in the current directory, segregated into subdirectories named .oauth.{email}.json.

These parameters offer necessary adaptability when deploying in varied operational environments or when managing numerous credential sets concurrently.

Example invocation:

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

Development Lifecycle

Building and Distribution

To prepare the module for release:

1. Ensure dependencies are synchronized and the lock file is updated:

bash uv sync

1. Compile the necessary distribution packages:

bash uv build

This action generates binary and source distributions within the dist/ folder.

1. Upload to the PyPI repository:

bash uv publish

Note: Authentication credentials (token, or username/password) must be provided via environment variables or flags (e.g., --token or UV_PUBLISH_TOKEN).

Troubleshooting and Diagnostics

Debugging inter-process communication over stdio can be difficult. For optimal diagnostic capabilities, utilizing the MCP Inspector is highly recommended.

You can initiate the Inspector via npm:

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

Upon launch, the Inspector console will provide a browser link to begin the debugging session.

Alternatively, observe the server logs directly:

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

== Contextual Information on Business Management Technology ==

Business operational tools encompass all the applications, control mechanisms, computational methods, and frameworks utilized by organizations to successfully navigate evolving marketplace conditions, maintain competitive advantage, and enhance overall organizational efficiency. (Derived from Wikipedia)

== Functional Taxonomy of Management Tools ==

These instruments can be segmented based on the organizational function they serve, covering areas such as resource allocation, workflow oversight, documentation, personnel management, strategic formulation, and performance monitoring. Core functional categories include:

• Data acquisition and validation utilities.
• Process monitoring and refinement systems.
• Aggregation tools for data synthesis and executive decision support.

Modern management technology has undergone rapid transformation, making optimal selection a challenge due to constant pressure for cost reduction, revenue growth, deeper customer insight attainment, and superior product fulfillment.

== Prominent Business Tool Categories (2013 Survey Highlights) ==

Major recognized tools often include:

• Strategic Planning Frameworks
• Client Relationship Management (CRM)
• Personnel Satisfaction Measurement
• Competitive Analysis (Benchmarking)
• Performance Measurement Systems (Balanced Scorecard)
• Core Competency Definition
• Operational Restructuring (Outsourcing)
• Organizational Transformation Programs
• Logistics and Procurement Oversight (SCM)
• Foundational Mandates (Mission/Vision)
• Market Segmentation Analysis
• Comprehensive Quality Improvement Methodologies (TQM)

== Business Software Applications ==

Business software refers to computational programs designed to execute specific corporate activities—boosting productivity, accurately measuring outcomes, and automating tasks. This domain has progressed from foundational Management Information Systems (MIS) to comprehensive Enterprise Resource Planning (ERP), later integrating CRM functionality, and now largely resides in cloud-based management solutions. Value addition relies not just on IT investment but critically on effective deployment strategies and precise tool selection relative to organizational demands.