home / mcp / google workspace mcp server

Google Workspace MCP Server

Provides full Calendar, Contacts, and Gmail management via OAuth2 for Claude Desktop and other AI agents.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "199-mcp-mcp-google": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-google"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "YOUR_CLIENT_ID.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/credentials.json",
        "GOOGLE_CALENDAR_MCP_TOKEN_PATH": "/path/to/tokens"
      }
    }
  }
}

This MCP server lets Claude Desktop and other AI agents fully manage Google Calendar, Contacts, and Gmail through a unified, OAuth2-secured interface. It supports creating, updating, deleting, and organizing data across Calendar, Contacts, and Gmail, enabling powerful automation for AI-assisted workflows.

How to use

You interact with the Google Workspace MCP server through a client that supports MCP servers. Create an MCP configuration that points at this server, then start the server locally or point your client at a remote MCP URL if available. Use the calendar, contact, and Gmail endpoints to perform actions such as creating events, listing contacts, or reading emails. The server handles authentication, token refresh, and unified permission scopes for Calendar, Contacts, and Gmail.

How to install

Prerequisites: Node.js and npm installed on your machine. You will run a small command to install or run the MCP server.

Option 1: Run directly with npx (recommended)

npx mcp-google

Option 2: Install globally with npm

npm install -g mcp-google

After installing, you start the MCP server by invoking the command shown in the Option 1 snippet above or the corresponding global install usage. The server will guide you through authentication prompts in your browser.

Security and configuration notes

Authentication is handled via OAuth2 with automatic token refresh. You configure your Google OAuth credentials in Google Cloud Console and supply them to the MCP server configuration environment. Tokens are stored securely for future use.

Environment variables to configure (examples): Google client credentials and optional token paths. Use the environment blocks shown in the configuration examples to supply these values.

Configuration examples

Below are example configurations for running the MCP server from a client. Use one of these in your MCP client config to connect to the server.

json
{
  "mcpServers": {
    "google_workspace": {
      "command": "npx",
      "args": ["-y", "mcp-google"],
      "env": {
        "GOOGLE_CLIENT_ID": "YOUR_CLIENT_ID.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/credentials.json",
        "GOOGLE_CALENDAR_MCP_TOKEN_PATH": "/path/to/tokens"
      }
    }
  }
}

If you prefer to provide credentials directly as environment variables without a credentials.json file, use this variation.

json
{
  "mcpServers": {
    "google_workspace": {
      "command": "npx",
      "args": ["-y", "mcp-google"],
      "env": {
        "GOOGLE_CLIENT_ID": "YOUR_CLIENT_ID.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

Notes on authentication setup

Follow the Google Cloud Console steps to create OAuth 2.0 credentials for a desktop app, enable the Calendar and People APIs, and configure the OAuth consent screen. When you start the MCP server, a browser window will prompt you to authenticate and grant access to Calendar, Contacts, and Gmail.

Available tools

list-calendars

Retrieve all accessible calendars with their properties such as id, summary, and primary status.

list-events

List events from one or more calendars with filters for time range, text search, and attendee status.

create-event

Create a new calendar event with support for single or recurring events, attendees, and notifications.

update-event

Update details of existing events, including recurring rule adjustments and attendee changes.

delete-event

Delete events from one or more calendars.

search-events

Search events across calendars using text queries and filters.

get-freebusy

Query free/busy information across multiple calendars to check availability.

list-contacts

List and search Google Contacts with pagination support.

get-contact

Retrieve detailed information for a specific contact.

create-contact

Create new contacts with names, emails, phones, addresses, and organizational data.

update-contact

Update existing contact fields such as emails, phones, and addresses.

delete-contact

Remove contacts from Google Contacts.

list-emails

Search and list Gmail messages using advanced queries.

get-email

Read full email content including body and attachments.

send-email

Send new emails or replies with HTML support.

update-email

Modify email properties like labels, read status, and star status.

delete-email

Move emails to trash or permanently delete.

create-draft

Create email drafts for later editing and sending.

update-draft

Edit existing email drafts.

send-draft

Send a saved draft as a real email.

list-labels

List Gmail labels/folders.

create-label

Create new Gmail labels for organizing emails.

update-label

Update label properties and colors.

delete-label

Remove Gmail labels.

batch-update-emails

Perform bulk operations on multiple emails in a single action.