mcp-gsuite

Purpose

mcp-gsuite is an MCP server used to interact with Google Workspace (G Suite) products. According to the repository information, it currently supports integration with Gmail and Google Calendar, aiming to enable AI assistants to read and process emails and manage schedules.

Main Capabilities

Gmail

• Supports multiple Google accounts.
• Retrieves current Gmail user information.
• Searches emails using flexible conditions, such as: unread emails, from a specific sender, date range, with attachments, etc.
• Retrieves full email content by email ID.
• Creates new draft emails, with configurable recipients, subject, body, and CC.
• Deletes draft emails.
• Replies to existing emails, with the option to send immediately or save as a draft.
• Retrieves multiple emails at once by multiple email IDs.
• Saves multiple attachments from emails to the local system.

Google Calendar

• Manages multiple calendars.
• Retrieves calendar events within a specified time range.
• Creates calendar events, with configurable: title, start/end time; optional location and description; optional attendees; custom time zone support; notification preferences.
• Deletes calendar events.

Example Prompts

The repository provides some example prompts to try:

• Retrieve my latest unread messages
• Search for emails from the Scrum Master
• Retrieve all emails from accounting
• Retrieve emails about ABC and summarize them
• Write a friendly reply to Alice's last email and upload the draft
• Reply to Bob's email with a thank-you note and save it as a draft
• What is on my schedule tomorrow?
• Check my family calendar on my personal account next week
• I need to plan a 2-hour event with Tim next week. Suggest some time slots.

Usage

Install via Smithery

mcp-gsuite can be automatically installed for Claude Desktop via Smithery.

Authentication Setup

Google Workspace (G Suite) APIs require OAuth2 authorization. Authentication must be set up according to the following steps:

1. Create OAuth2 credentials: Go to Google Cloud Console; create a new project or select an existing project; enable the Gmail API for the project and Google Calendar API; go to "Credentials" → "Create Credentials" → "OAuth client ID"; select "Desktop app" or "Web application" as the application type; configure the OAuth consent screen and fill in the required information; add authorized redirect URIs (for local development, include http://localhost:4100/code）。
2. Create .gauth.json in the working directory, containing the client information.
3. Create .accounts.json, containing the account information. Multiple accounts can be specified, and ensure they have access permissions in the Google Auth app. The extra_info field is especially worth noting, because you can add account information there that you want the AI to know (for example, whether it has a specific calendar).

Note: The first time a tool is executed for an account, a browser will open, redirect to Google, and ask for credentials, permission scopes, etc. After a successful login, the credentials will be stored in the local file .oauth.{email}.json. Once authorization is complete, a refresh token will be used.

Claude Desktop Configuration File Locations

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

You can also use uv run mcp-gsuite --accounts-file /path/to/custom/.accounts.json to specify a different account file, or use --credentials-dir /path/to/custom/credentials to specify a different credentials directory.

Configuration Options

This MCP server can be configured with custom paths for authentication and account information via multiple command-line options:

• --gauth-file: specifies the path to the .gauth.json containing the OAuth2 client configuration, defaulting to ./.gauth.json。
• --accounts-file: specifies the path to the .accounts.json containing the Google account information, defaulting to ./.accounts.json。
• --credentials-dir: Specifies the directory where OAuth credentials are stored after successful authentication. The default is a subdirectory for each account under the current working directory, with the filename being .oauth.{email}.json.

These options facilitate managing credentials and accounts across different environments or multiple sets, and are especially suitable for development and testing scenarios. This configuration is particularly useful when you run multiple server instances with different configurations, or deploy to environments where the default path is not appropriate.

Build and Release

To prepare a distribution package:

• Sync dependencies and update the lock file.
• Build the package distribution: this will create the source package and wheel package in the dist/ directory.
• Publish to PyPI: note that PyPI credentials need to be set 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 the MCP server runs via stdio, debugging can be challenging. For the best debugging experience, using MCP Inspector is strongly recommended. It can be started via an npm command, and the Inspector will display a URL that can be accessed in a browser to begin debugging. Server logs can also be viewed via a command.

Use Cases

• Have an AI assistant help handle Gmail emails: search, read, summarize, draft, and reply to emails.
• Have an AI assistant manage Google Calendar: view schedules, create and delete events, and find suitable time slots.
• Scenarios that require switching between multiple Google accounts.

Limitations

• Only covers Gmail and Google Calendar; other Google products are not currently supported.
• Relies on Google Workspace API and OAuth2 authentication; users need to configure the application and credentials themselves in the Google Cloud Console.
• The first use of each account requires completing authorization through a browser.
• Information such as fees and pricing is not currently provided.