fastmcp-gsuite

fastmcp-gsuite is an MCP server that bridges Google Workspace (Gmail and Google Calendar) with the MCP protocol, allowing you to manage and interact with your Google accounts through MCP prompts. It supports multiple Google accounts and exposes capabilities to query emails (including search by sender, date ranges, unread status, and attachments), retrieve full email content by ID, create and manage drafts, delete drafts, and compose and send (or store as drafts) replies. For Calendar, you can manage multiple calendars, fetch events within time ranges, create events with titles, times, locations, descriptions, attendees, time zones, and notification preferences, and delete events. The server is implemented using the fastmcp library and is a fork of the original mcp-gsuite project, updated to integrate with the fastmcp framework and modern configuration approaches.

To use the server, run it through the MCP launcher (via uv/uvx as shown in the config). The server relies on OAuth2 credentials for Google APIs. Configuration is now primarily driven by environment variables or a .env file, including paths to OAuth configuration, accounts, and credential storage. You can authenticate through an interactive setup workflow or use manual setup guided by the README. After setup, the server will expose prompts and tools for Gmail and Calendar operations that you can invoke via the MCP interface, such as retrieving unread messages, listing calendar events, creating drafts, or scheduling events.

Prerequisites:

• Python 3.8+ (or compatible runtime)
• pip and/or uv/uvx installed
• Access to Google Cloud Console for OAuth2 credentials (desktop app) and consent screen configured for Gmail, Calendar, and Drive APIs

Installation steps (recommended):

1. Install the package (Python) with interactive setup support: uv install fastmcp-gsuite or if using standard pip-based setup: pip install fastmcp-gsuite

2. Run the interactive setup to configure OAuth and accounts: uv run fastmcp-gsuite-setup

3. Follow prompts to authenticate Google accounts and generate the required configuration files (.gauth.json and .accounts.json). You can add accounts or list/remove them via the setup utility: uv run fastmcp-gsuite-setup --add-account uv run fastmcp-gsuite-setup --list uv run fastmcp-gsuite-setup --remove-account user@example.com

4. Run the server (as published, via the MCP launcher): uvx fastmcp-gsuite

Optional manual setup (advanced):

• Create .gauth.json with your OAuth client details as shown in the README
• Create .accounts.json with your Google account entries
• Export environment variables or use a .env file to point to these config files (GAUTH_FILE, ACCOUNTS_FILE, CREDENTIALS_DIR)

Notes:

• The setup wizard will guide you through authorizing Google accounts and generating credentials in your working directory.
• After initial setup, you can rely on environment variables or a .env file for configuration, rather than command-line arguments.

Configuration is primarily handled via environment variables or a .env file in the working directory. Key variables include:

• GAUTH_FILE: Path to the .gauth.json containing OAuth client configuration (default: ./ .gauth.json)
• ACCOUNTS_FILE: Path to the .accounts.json containing Google account information (default: ./ .accounts.json)
• CREDENTIALS_DIR: Directory to store generated .oauth2.{email}.json credentials (default: .)

Common issues and tips:

• If you encounter "No refresh token received" during setup, revoke the app’s access in Google Account permissions and re-run the setup.
• If the browser doesn’t open automatically during interactive setup, ensure popups are allowed or run the setup again.
• Ensure your Google Cloud project has Gmail API, Calendar API, and Drive API enabled and that OAuth2 client IDs are configured for Desktop/Installed applications.
• For multiple accounts, leverage the accounts.json structure to keep track of each account’s metadata and use the setup utilities to manage them.