mcp-gsuite

MCP.Pizza Chef: MarkusPfundstein

The mcp-gsuite MCP server provides robust integration with Google G Suite products, specifically Gmail and Calendar. It supports multiple Google accounts, allowing users to manage emails and calendar events efficiently. Features include querying and retrieving emails with flexible search parameters, managing drafts, replying to emails, and handling attachments. For Calendar, it enables managing multiple calendars, retrieving events within time ranges, and creating events with detailed attributes such as title, time, location, and attendees. This server facilitates real-time, structured interaction with Google productivity tools, enhancing workflow automation and AI-assisted task management.

Use This MCP server To

Manage multiple Google accounts for Gmail and Calendar Query and retrieve emails with advanced search filters Create, delete, and reply to Gmail drafts Download email attachments to local storage Retrieve and manage calendar events by date range Create detailed calendar events with attendees and location

README

mcp-gsuite MCP server

smithery badge MCP server to interact with Google products.

Example prompts

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

  1. General
  • Multiple google accounts
  1. Gmail
  • Get your Gmail user information
  • Query emails with flexible search (e.g., unread, from 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 (can either send immediately or save as draft)
  • Retrieve multiple emails at once by their IDs.
  • Save multiple attachments from emails to your local system.
  1. 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 you can 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. 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

Install

Installing via Smithery

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

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

Oauth 2

Google Workspace (G Suite) APIs require OAuth2 authorization. Follow these steps to set up authentication:

  1. 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 for your project
    • Go to "Credentials" → "Create Credentials" → "OAuth client ID"
    • Select "Desktop app" or "Web application" as the application type
    • Configure the OAuth consent screen with required information
    • Add authorized redirect URIs (include http://localhost:4100/code for local development)
  2. Required OAuth2 Scopes:

   [
     "openid",
     "https://mail.google.com/",
     "https://www.googleapis.com/auth/calendar",
     "https://www.googleapis.com/auth/userinfo.email"
   ]
  1. Then create a .gauth.json in your working directory with client
{
    "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. Create a .accounts.json file with account information
{
    "accounts": [
        {
            "email": "alice@bob.com",
            "account_type": "personal",
            "extra_info": "Additional info that you want to tell Claude: E.g. 'Contains Family Calendar'"
        }
    ]
}

You can specifiy multiple accounts. Make sure they have access in your Google Auth app. The extra_info field is especially interesting as you can add info here that you want to tell the AI about the account (e.g. whether it has a specific agenda)

Note: When you first execute one of the tools for a specific account, a browser will open, redirect you to Google and ask for your credentials, scope, etc. After a successful login, it stores the credentials in a local file called .oauth.{email}.json . Once you are authorized, the refresh token will be used.

Claude Desktop

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json

On 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"
      ]
    }
  }
}

Note: You can also use the uv run mcp-gsuite --accounts-file /path/to/custom/.accounts.json to specify a different accounts file or --credentials-dir /path/to/custom/credentials to specify a different 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 server can be configured with several command-line options to specify custom paths for authentication and account information:

  • --gauth-file: Specifies the path to the .gauth.json file containing OAuth2 client configuration. Default is ./.gauth.json.
  • --accounts-file: Specifies the path to the .accounts.json file containing information about the Google accounts. Default is ./.accounts.json.
  • --credentials-dir: Specifies the directory where OAuth credentials are stored after successful authentication. Default is the current working directory with a subdirectory for each account as .oauth.{email}.json.

These options allow for flexibility in managing different environments or multiple sets of credentials and accounts, especially useful in development and testing scenarios.

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

This configuration is particularly useful when you have multiple instances of the server running with different configurations or when deploying to environments where the default paths are not suitable.

Development

Building and Publishing

To prepare the package for distribution:

  1. Sync dependencies and update lockfile:
uv sync
  1. Build package distributions:
uv build

This will create source and wheel distributions in the dist/ directory.

  1. Publish to PyPI:
uv publish

Note: 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

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.

You can launch the MCP Inspector via npm with this command:

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

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.

You can also watch the server logs with this command:

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

mcp-gsuite FAQ

How do I authenticate multiple Google accounts with mcp-gsuite?
mcp-gsuite supports OAuth 2.0 authentication for multiple Google accounts, allowing you to switch and manage them seamlessly within the server.
Can I search emails by specific criteria using mcp-gsuite?
Yes, you can query emails using flexible search parameters such as unread status, sender, date ranges, and attachment presence.
Is it possible to create and manage email drafts through mcp-gsuite?
Absolutely, you can create new drafts, delete existing ones, and reply to emails either by sending immediately or saving as drafts.
How does mcp-gsuite handle calendar event creation?
You can create calendar events with detailed information including title, start/end times, location, description, and optional attendees.
Can mcp-gsuite save email attachments locally?
Yes, it supports saving multiple attachments from emails directly to your local system.
Does mcp-gsuite support retrieving multiple emails or events at once?
Yes, it can retrieve multiple emails by their IDs and fetch calendar events within specified time ranges.
What Google products are currently supported by mcp-gsuite?
Currently, mcp-gsuite supports Gmail and Google Calendar integration.
Is mcp-gsuite compatible with LLM providers like OpenAI, Claude, and Gemini?
Yes, mcp-gsuite can be integrated with various LLM providers including OpenAI, Claude, and Gemini for enhanced AI workflows.