SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI productivitygoogle-mcp

google-mcp

Tools for Gmail, Google Calendar, Google Drive and Google Tasks.

Open website

About this tool

Purpose

google-mcp is a collection of Google-native tools for the MCP (Model Context Protocol), designed to integrate seamlessly with AI clients such as Claude and Cursor. It wraps Google services such as Gmail, Google Calendar, Google Drive, and Google Tasks into tools that AI can call, letting users drive these services with natural language to complete everyday operations. The project supports one-click installation via .mcpb and also provides a manual installation method.

Main Capabilities

Gmail

  • Send emails, supporting multiple recipients (to, cc, bcc), with attachments addable from local files or Google Drive.
  • Download email attachments to local storage, with cross-platform support.
  • List emails by custom query, labels, and number of results.
  • Read a specified email by ID and display attachment information.
  • Manage labels (add, remove, list).
  • Create drafts and delete emails.

Calendar

  • List calendars and set the default calendar.
  • Create events with details such as summary, start/end time, and participants.
  • List upcoming events by customizable filters.
  • Update or delete existing events.
  • Find free time slots available for scheduling.

Drive

  • Filter using search queries.
  • Sort by modified date or other criteria.
  • Customize the number displayed.
  • View detailed file metadata.
  • Read file contents (text, documents, spreadsheets).
  • Create new files with specified content.
  • Update existing files.
  • Delete files (move to trash or permanently delete).
  • Share files with specified permissions.

Tasks

  • View all task lists.
  • Create new task lists.
  • Delete existing task lists.
  • Set the default task list.
  • List tasks by filters.
  • View task details.
  • Create tasks with titles, notes, and due dates.
  • Update task attributes.
  • Mark tasks as completed.
  • Delete tasks.

Other

  • Google Contacts: search and manage contacts.
  • More features are still planned (TODO Plans).

New Features in v1.1.0

Email Attachment Support

  • Send emails withattachments from local files or Google Drive.
  • Download all email attachments to local storage.
  • Dual attachment sources: local file paths or Google Drive file IDs.
  • Smart file handling: automatically detects MIME types and cleans up file names.

Enhanced Email Capabilities

  • Multi-source attachments: the same email can attach files from both local storage and Google Drive at the same time.
  • Custom file names: can override the original file names of attachments.
  • File size validation: automatically enforces Gmail's 25MB limit.
  • Cross-platform downloads: automatically detects the Downloads folder on Windows, macOS, and Linux.
  • Conflict resolution: automatically renames files to prevent overwriting.

New and Enhanced Tools

  • google_gmail_send_email: now supports attachments from local files and Google Drive.
  • google_gmail_draft_email: create drafts with attachments.
  • google_gmail_download_attachments: download all email attachments, with customizable paths.

OAuth Management

  • Automatically refresh expired access tokens.
  • Update tokens in the token file without re-authentication.
  • Complete re-authentication through automatic token cleanup.
  • Maintain session continuity during long-running operations.

Usage

One-Click Installation

The project provides a .mcpb one-click installation method.

Manual Installation

Prerequisites: install Bun:

brew install oven-sh/bun/bun # macOS/Linux with Homebrew

Set up OAuth:

  1. Create a Google Cloud project in the Google Cloud Console.
  2. Set up OAuth 2.0 credentials (Client ID, Client Secret).
  3. Select Desktop app as the type.
  4. If using test mode, add your email address to the test users list.
  5. Make sure API access is enabled for the required services (Gmail, Calendar, Drive, etc.).

Configure the client: edit claude_desktop_config.json (or the corresponding configuration file for your client).

Authentication: the first time you run the server, a browser will open for OAuth authentication. Grant access as prompted, and the token will be saved to GOOGLE_OAUTH_TOKEN_PATH.

After that, you can let Claude use the google-mcp tools.

Command chaining

You can chain commands to form workflows, for example: "List my unread emails, draft a reply to the latest one, and schedule a follow-up meeting tomorrow at 2 PM."

Managed deployment

A managed deployment is available on Fronteir AI.

OAuth token management

The server has built-in OAuth token management and can gracefully handle expired access tokens:

  • Automatic token refresh: when an access token expires, it can be refreshed without going through the full OAuth flow again.
  • Full re-authentication: automatically handles cases where the refresh token is invalid or expired.
  • Persistent storage: refreshed tokens are automatically saved to the configured token file path.
  • Session continuity: after refresh, all Google services are reinitialized with the new token.

Refresh token: if you encounter an authentication error or want to proactively refresh the token, simply ask:

  • Use the stored refresh token to obtain a new access token
  • Update the token file with the new credentials
  • Reinitialize all Google services with the new authentication
  • Display the new token expiration time

Full re-authentication: if you encounter an invalid_grant error or the refresh token has expired, you can start over. This automated flow will:

  • Delete the existing token from the token file
  • Start the OAuth server to handle the callback
  • Open the browser for a fresh authentication
  • Automatically save the new token
  • Reinitialize services with the new credentials

You only need to click "Allow" in the browser; everything else is automated. Note: if there is no valid refresh token, you need to go through the initial OAuth authentication flow again.

Transport support

This MCP server supports both stdio and HTTP transports via environment variables:

  • Stdio transport (default)
  • HTTP transport (Streamable HTTP)

Endpoints in HTTP mode:

  • GET /health - health check endpoint, including session count
  • GET /mcp - session information and server status
  • POST /mcp - main MCP JSON-RPC endpoint, used to send requests
  • DELETE /mcp - session termination endpoint

Session management: the Streamable HTTP transport uses the official MCP SDK and has automatic session management:

  • Automatic sessions: the server automatically generates secure session IDs
  • SSE streaming: supports Server-Sent Events for real-time communication
  • JSON responses: falls back to JSON responses when SSE is unavailable
  • DNS protection: built-in security feature for production deployments

HTTP transport configuration: when configuring a client for HTTP transport, use the server URL.

Use cases

  • Manage Gmail messages, attachments, labels, and drafts in natural language in an AI client.
  • Schedule calendar events and find free time through an AI assistant.
  • Browse, read, create, update, and share Google Drive files.
  • Manage Google Tasks task lists and tasks.
  • Chain multiple Google service operations into automated workflows.

Limitations

  • You need to create a Google Cloud project yourself and configure OAuth 2.0 credentials.
  • When using test mode, you need to add your email address to the test users list.
  • You need to enable API access for the required services.
  • Gmail attachments have a 25MB size limit.
  • Manual installation requires installing Bun first.
  • Some features (such as more tools beyond Google Contacts) are still in the TODO planning stage.

Related tools

Browse category