📌Overview

Purpose: To provide an MCP server that facilitates seamless interaction with Google products, specifically Gmail and Calendar.

Overview: The mcp-gsuite server is designed to integrate with multiple Google accounts, enabling users to manage their Gmail and Calendar activities effectively. It supports robust functionalities for retrieving, sending, and organizing emails, as well as managing calendar events with user-defined parameters.

Key Features:

Multiple Google Accounts Support: Manage more than one Google account, making it easier to handle personal and professional tasks without needing to log in and out.
Gmail Integration: Access user information, conduct flexible email searches, create, retrieve, and manage drafts, reply to emails, and save attachments locally, enhancing email management efficiency.
Calendar Management: Organize and retrieve events, create new events with customizable details (including attendees and notifications), and efficiently manage multiple calendars for better scheduling.

mcp-gsuite MCP server

MCP server to interact with Google products.

Supported Features

Currently, this MCP server supports Gmail and Calendar integration with the following capabilities:

General

Multiple Google accounts

Gmail

Get Gmail user information
Query emails with flexible search (e.g., unread, specific senders, date ranges, with attachments)
Retrieve complete email content by ID
Create new draft emails with recipients, subject, body, and CC options
Delete draft emails
Reply to existing emails (send immediately or save as draft)
Retrieve multiple emails at once by their IDs
Save multiple attachments from emails to your local system

Calendar

Manage multiple calendars
Get calendar events within specified time ranges
Create calendar events with:
- Title, start/end times
- Optional location and description
- Optional attendees
- Custom timezone support
- Notification preferences
Delete calendar events

Example prompts to try

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 and store it as 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

Quickstart

Installing via Smithery

To install mcp-gsuite for Claude Desktop automatically via Smithery:

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

OAuth 2 Setup

Google Workspace (G Suite) APIs require OAuth2 authorization. Follow these steps:

Create OAuth2 Credentials:
- Go to the Google Cloud Console
- Create a new project or select an existing one
- Enable the Gmail API and Google Calendar API
- Go to "Credentials" → "Create Credentials" → "OAuth client ID"
- Select "Desktop app" or "Web application"
- Configure the OAuth consent screen
- Add authorized redirect URIs (include http://localhost:4100/code for local development)
Required OAuth2 Scopes:

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

Create .gauth.json:

{
    "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 .accounts.json:

{
    "accounts": [
        {
            "email": "alice@bob.com",
            "account_type": "personal",
            "extra_info": "Additional info to tell Claude, e.g. 'Contains Family Calendar'"
        }
    ]
}

You can specify multiple accounts. The extra_info field allows you to provide additional context to the AI about the account.

Note: When first executing for a specific account, a browser will open to authorize access. Credentials are saved locally as .oauth.{email}.json for reuse.

Claude Desktop Config Paths

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

Server Configuration

Development / Unpublished Servers

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

Use options to specify custom 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

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

Command-line Configuration Options

--gauth-file: Path to the .gauth.json OAuth2 client config file. Default ./.gauth.json.
--accounts-file: Path to the .accounts.json account info file. Default ./.accounts.json.
--credentials-dir: Directory storing OAuth credentials after authentication. Default is current working directory.

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

Building and Publishing

Sync dependencies and update lockfile:

uv sync

Build package distributions (dist/ directory created):

uv build

Publish to PyPI (set credentials via environment variables or flags):

uv publish

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

Debugging

MCP servers run over stdio, so debugging can be difficult. It's recommended to use the MCP Inspector:

Launch with npm:

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

The Inspector will provide a URL accessible in your browser for debugging.

To watch server logs (example for MacOS):

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