Google MCP Tools

You use Google MCP Tools to connect your Google services (Gmail, Calendar, Drive, and more) to your AI client through the MCP protocol. This enables you to automate email, calendar, file, and task workflows from a single, consistent interface while handling authentication and token management for long-running interactions.

How to use

Set up your MCP client to talk to the google_mcp server, then start issuing commands through natural-language prompts or structured requests. You can chain actions like listing unread emails, drafting replies, scheduling follow-ups, creating calendar events, and saving attachments from Gmail to local storage or Drive. Use the client to perform multi-service workflows in a single session, such as:

• List my unread emails, draft a reply to the latest one, and schedule a follow-up meeting tomorrow at 2 PM.
• Create a calendar event based on an email discussion and attach relevant Gmail attachments.
• Download all attachments from a set of emails and save them to a local or Drive location. The server maintains OAuth tokens automatically, refreshing them as needed so you can run long-running automation without re-authenticating frequently.

How to install

Prerequisites you need before starting:

• Bun: a fast JavaScript runtime used to run the MCP server.
• A Google Cloud project with OAuth credentials if you plan to use OAuth-based authentication.

Install Bun on macOS or Linux: brew install oven-sh/bun/bun # macOS/Linux with Homebrew

Start the local MCP server in stdio mode using the documented runtime command. This runs the server directly in your environment and uses the provided configuration to launch the Google MCP tools.

Run the server in HTTP mode when you want streamable HTTP transport for MCP clients. You’ll expose an HTTP endpoint that your client can reach to send requests.

Configuration snippets you can copy into your client config or environment (examples shown for stdio and HTTP transports):

Configuration and transport

stdio transport (default) uses a local command to start the MCP server.

http transport (streamable HTTP) exposes endpoints for health checks, session management, and the main MCP RPC interface.

{
  "mcpServers": {
    "google-mcp": {
      "command": "bunx",
      "args": ["--no-cache", "google-mcp@latest"],
      "env": {
        // Either can be used, but not both
        // Use OAuth
        "GOOGLE_OAUTH_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "GOOGLE_OAUTH_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "GOOGLE_OAUTH_TOKEN_PATH": "<PATH_TO_STORE_TOKENS> CAN_BE_ANYWHERE_ON_YOUR_SYSTEM",
        // Use Service Account
        "GOOGLE_CLIENT_EMAIL": "<YOUR_SERVICE_ACCOUNT_EMAIL>",
        "GOOGLE_PRIVATE_KEY": "<YOUR_SERVICE_ACCOUNT_PRIVATE_KEY>",
        "GMAIL_USER_TO_IMPERSONATE": "<USER_TO_IMPERSONATE>"
      }
    }
  }
}

HTTP transport configuration example for clients to connect to a remote MCP server:

{
  "mcpServers": {
    "google-mcp-http": {
      "url": "http://localhost:3000/mcp",
      "type": "http",
      "args": []
    }
  }
}

Notes on token management and security

The server includes built-in OAuth token management with automatic refresh and re-authentication support. Tokens are persisted to the configured token file and reused across sessions, ensuring continuity for long-running workflows.

If you need to refresh tokens manually, you can trigger a refresh and reinitialize services so all components run with fresh credentials.

Examples of supported actions

Gmail: send emails with attachments from local files or Google Drive, download all attachments, manage labels, read messages, draft and delete emails.

Calendar: list calendars, create/update/delete events, find free time slots, and set a default calendar.

Drive: read and write files, read content for various file types, create new files with specified content, update and delete files, and manage sharing permissions.

Tasks: view task lists, create tasks with details and due dates, update and delete tasks, and mark tasks as complete.

Troubleshooting and tips

If you encounter authentication errors, try refreshing tokens or re-authenticating to obtain new credentials and reinitialize services.

For HTTP transport, ensure the server URL is reachable and that the MCP client is configured to point to the /mcp endpoint.

Tools and capabilities

Gmail sends and drafts emails with attachment support and attachment downloads.

Available tools

google_gmail_send_email

Send emails via Gmail with multiple recipients and optional attachments from local files or Google Drive.

google_gmail_draft_email

Create email drafts with attachments from local storage or Google Drive.

google_gmail_download_attachments

Download all email attachments to local storage with cross-platform path handling.

google_calendar_list_events

List upcoming calendar events with filters and limits.

google_calendar_create_event

Create calendar events with details like time, attendees, and description.

google_drive_read_file

Read file contents and metadata from Google Drive.

google_drive_create_file

Create new Google Drive files with specified content.

google_drive_update_file

Update existing Google Drive files.

google_drive_delete_file

Delete files from Google Drive (move to trash or permanent delete).

google_tasks_list

View task lists and tasks with filters.

google_tasks_create

Create tasks with title, notes, and due dates.

google_tasks_update

Update task properties and status.

google_tasks_complete

Mark tasks as complete.

google_contacts_search

Search and manage Google Contacts.