Overview

MCP GSuite enables Claude to interact with Google Workspace services, providing a powerful interface to Gmail and Google Calendar. This integration allows you to manage your emails and calendar events through natural language conversations with Claude.

Features

Gmail Integration

• Query emails with flexible search parameters (unread, sender, date ranges, attachments)
• Retrieve complete email content
• Create and manage draft emails
• Reply to existing emails
• Save attachments to your local system

Calendar Integration

• Manage multiple calendars
• View upcoming events within specified time ranges
• Create calendar events with customizable parameters
• Delete calendar events

Multi-Account Support

• Configure and use multiple Google accounts
• Add custom information about each account for Claude's context

Installation

Option 1: Install via Smithery (Recommended)

The easiest way to install MCP GSuite is through Smithery:

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

Option 2: Manual Installation

1. Install the package using pip or uv:

   pip install mcp-gsuite
   # or
   uv pip install mcp-gsuite
   

2. Configure Claude Desktop to use the MCP server (see Configuration section below)

Configuration

1. Set Up Google OAuth2 Credentials

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

2. Create Configuration Files

Create a .gauth.json file in your working directory:

{
    "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"
    }
}

Create a .accounts.json file with your account information:

{
    "accounts": [
        {
            "email": "your.email@gmail.com",
            "account_type": "personal",
            "extra_info": "Contains Family Calendar and Work emails"
        },
        {
            "email": "your.work@company.com",
            "account_type": "work",
            "extra_info": "Work account with meeting schedules"
        }
    ]
}

3. Configure Claude Desktop

Edit your Claude Desktop configuration file:

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

Add the following configuration:

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

For custom configuration paths:

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

Authentication

When you first use a tool for a specific account, a browser window will open requesting Google authentication. After successful login, the credentials will be stored locally in a file named .oauth.{email}.json. For subsequent uses, the refresh token will be used automatically.

Example Prompts

Try these prompts with Claude to test the integration:

• "Retrieve my latest unread messages"
• "Search my emails from the Scrum Master"
• "Take the email about the quarterly report and summarize it"
• "Write a response to Alice's last email and save it as a draft"
• "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."

Advanced Configuration Options

The MCP server supports several command-line options:

• --gauth-file: Path to the .gauth.json file (default: ./.gauth.json)
• --accounts-file: Path to the .accounts.json file (default: ./.accounts.json)
• --credentials-dir: Directory for storing OAuth credentials (default: current working directory)

Example:

uvx mcp-gsuite --gauth-file /path/to/.gauth.json --accounts-file /path/to/.accounts.json --credentials-dir /path/to/credentials

Required OAuth2 Scopes

The following OAuth scopes are required for full functionality:

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

Troubleshooting

• Authentication Issues: Ensure your OAuth credentials are correctly configured and that you've granted all required permissions.
• Missing Emails: Check your search parameters and ensure you're using the correct account.
• Calendar Events Not Showing: Verify that you have access to the calendar and that the time range is correctly specified.
• Connection Errors: Check your internet connection and ensure the MCP server is running.

If problems persist, try removing the .oauth.{email}.json file and re-authenticating.