Connecting LLMs to Google Workspace: A Deep Dive into the mcp-gsuite MCP Server

The mcp-gsuite server bridges the gap between Large Language Models (LLMs) and Google Workspace, enabling powerful integrations with Gmail and Calendar through the Model Context Protocol (MCP). This document provides a comprehensive guide to understanding, installing, configuring, and developing with mcp-gsuite.

Core Capabilities

This MCP server empowers LLMs with the following functionalities:

1. General

• Multi-Account Support: Seamlessly manage and interact with multiple Google accounts.

2. Gmail

• User Information Retrieval: Obtain detailed information about Gmail users.
• Advanced Email Querying: Search emails based on various criteria, including:
  • Unread status
  • Sender
  • Date ranges
  • Attachments
• Email Content Retrieval: Access the complete content of emails by their unique IDs.
• Draft Management:
  • Create new draft emails with recipients, subject, body, and CC options.
  • Delete existing draft emails.
• Email Reply: Reply to emails directly, with options to send immediately or save as a draft.
• Batch Email Retrieval: Retrieve multiple emails simultaneously using their IDs.
• Attachment Handling: Save multiple attachments from emails to your local system.

3. Calendar

• Multi-Calendar Management: Manage events across multiple calendars.
• Event Retrieval: Get calendar events within specified time ranges.
• Event Creation: Create new calendar events with:
  • Title, start/end times
  • Optional location and description
  • Optional attendees
  • Custom timezone support
  • Notification preferences
• Event Deletion: Remove calendar events.

Getting Started

Installation via Smithery

The recommended installation method is through Smithery, which automates the process for Claude Desktop:

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

Manual Configuration: OAuth 2.0 and Account Setup

Google Workspace APIs require OAuth 2.0 for secure authorization. Follow these steps to configure authentication:

1. Create OAuth 2.0 Credentials:

• Navigate to the Google Cloud Console.
• Create a new project or select an existing one.
• Enable the Gmail API and Google Calendar API for your project.
• Go to "Credentials" → "Create Credentials" → "OAuth client ID".
• Choose "Desktop app" or "Web application" as the application type.
• Configure the OAuth consent screen with the necessary information.
• Add authorized redirect URIs (include http://localhost:4100/code for local development).

2. Required OAuth 2.0 Scopes:

Ensure the following OAuth 2.0 scopes are enabled for your application:

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

3. Create .gauth.json:

Create a .gauth.json file in your working directory with your OAuth 2.0 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"
  }
}

4. Create .accounts.json:

Create a .accounts.json file to define the Google accounts you want to use:

{
  "accounts": [
    {
      "email": "[email protected]",
      "account_type": "personal",
      "extra_info": "Contains Family Calendar"
    }
  ]
}

• You can specify multiple accounts in this file.
• The extra_info field is crucial for providing context to the LLM about each account (e.g., whether it contains a specific calendar).

Important: The first time you use a tool for a specific account, a browser window will open, redirecting you to Google for authentication. After successful login, the credentials are saved in a local file named .oauth.{email}.json. Subsequent requests will use the refresh token for authorization.

Claude Desktop Integration

To integrate mcp-gsuite with Claude Desktop, you need to configure the claude_desktop_config.json file. The location of this file varies depending on your operating system:

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

Development/Unpublished Servers Configuration

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

You can customize the paths to the accounts file and credentials directory:

{
  "mcpServers": {
    "mcp-gsuite": {
      "command": "uv",
      "args": [
        "--directory",
        "<dir_to>/mcp-gsuite",
        "run",
        "mcp-gsuite",
        "--accounts-file",
        "/path/to/custom/.accounts.json",
        "--credentials-dir",
        "/path/to/custom/credentials"
      ]
    }
  }
}

Published Servers Configuration

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

Configuration Options

The mcp-gsuite server offers several command-line options for customization:

• --gauth-file: Specifies the path to the .gauth.json file. Default: ./.gauth.json.
• --accounts-file: Specifies the path to the .accounts.json file. Default: ./.accounts.json.
• --credentials-dir: Specifies the directory for storing OAuth credentials. Default: current working directory with a subdirectory for each account as .oauth.{email}.json.

Example usage:

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 Workflow

Building and Publishing

1. Sync dependencies and update lockfile:

   uv sync

2. Build package distributions:

   uv build

   This creates source and wheel distributions in the dist/ directory.

3. Publish to PyPI:

   uv publish

   You'll need to set PyPI credentials via environment variables or command flags:

   • Token: --token or UV_PUBLISH_TOKEN
   • Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Debugging

Debugging MCP servers running over stdio can be complex. The recommended approach is to use the MCP Inspector.

Launch the MCP Inspector using:

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

The Inspector will provide a URL for browser-based debugging.

You can also monitor server logs using:

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

Example Prompts

Here are some example prompts to get you started:

Gmail:

• "Retrieve my latest unread messages."
• "Search my emails from the Scrum Master."
• "Retrieve all emails from accounting."
• "Take the email about ABC and summarize it."
• "Write a nice response to Alice's last email and upload a draft."
• "Reply to Bob's email with a Thank you note. Store it as draft."

Calendar:

• "What do I have on my agenda tomorrow?"
• "Check my private account's Family agenda for next week."
• "I need to plan an event with Tim for 2hrs next week. Suggest some time slots."

By following this guide, you can effectively leverage the mcp-gsuite server to create powerful LLM applications that seamlessly integrate with Google Workspace.