Google Workspace MCP server for AI agents

The Google Workspace MCP server provides a comprehensive interface for accessing Google Workspace services through AI assistants and developer tools. It enables natural language control over Gmail, Drive, Calendar, Docs, and more.

Installation

One-Click Claude Desktop Install (Recommended)

Download the latest google_workspace_mcp.dxt from the Releases page
Double-click the file to open Claude Desktop and click Install
In Claude Desktop, navigate to Settings → Extensions → Google Workspace MCP and paste your Google OAuth credentials
Start a new Claude chat and use any Google Workspace tool

Prerequisites

Python 3.10+
uvx (for instant installation) or uv (for development)
Google Cloud Project with OAuth 2.0 credentials

Google Cloud Setup

Create OAuth 2.0 credentials in Google Cloud Console:
- Create a new project or use an existing one
- Navigate to APIs & Services → Credentials
- Click Create Credentials → OAuth Client ID
- Choose Web Application as the application type
- Add redirect URI: http://localhost:8000/oauth2callback
Enable the necessary APIs in Google Cloud Console:
- Go to APIs & Services → Library
- Search for and enable Calendar, Drive, Gmail, Docs, Sheets, Slides, Forms, Tasks, Chat APIs

Configuration

Configure credentials using one of these methods:

Option A: Environment Variables (Recommended for Production)

export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
export GOOGLE_OAUTH_REDIRECT_URI="http://localhost:8000/oauth2callback"  # Optional

Option B: File-based (Traditional)

Download credentials as client_secret.json in project root
To use a different location, set GOOGLE_CLIENT_SECRET_PATH environment variable

Option C: .env File (Recommended for Development)

cp .env.oauth21 .env
# Edit .env to add your credentials

Additional environment variables:

export OAUTHLIB_INSECURE_TRANSPORT=1  # Development only
export [email protected]  # Optional: Default email for auth
export GOOGLE_PSE_API_KEY=your-custom-search-api-key  # Optional: For Google Custom Search
export GOOGLE_PSE_ENGINE_ID=your-search-engine-id  # Optional: For Google Custom Search

Starting the Server

# Default (stdio mode for MCP clients)
uv run main.py

# HTTP mode (for web interfaces and debugging)
uv run main.py --transport streamable-http

# Single-user mode (simplified authentication)
uv run main.py --single-user

# Selective tool registration
uv run main.py --tools gmail drive calendar tasks

Instant CLI with uvx

# Requires Python 3.10+ and uvx
export GOOGLE_OAUTH_CLIENT_ID="xxx"
export GOOGLE_OAUTH_CLIENT_SECRET="yyy"
uvx workspace-mcp --tools gmail drive calendar

OAuth 2.1 Support (Multi-User)

To enable OAuth 2.1 for multi-user support:

export MCP_ENABLE_OAUTH21=true
uv run main.py --transport streamable-http

Connect to Claude Desktop

Guided Setup (Recommended)

python install_claude.py

This script automatically configures Claude Desktop with your credentials.

Manual Claude Configuration

Open Claude Desktop Settings → Developer → Edit Config

Add the server configuration:

{
  "mcpServers": {
    "google_workspace": {
      "command": "uvx",
      "args": ["workspace-mcp"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret",
        "OAUTHLIB_INSECURE_TRANSPORT": "1"
      }
    }
  }
}

Available Tools

Google Calendar

list_calendars: List accessible calendars
get_events: Retrieve events with time range filtering
get_event: Fetch detailed information of a single event
create_event: Create events with optional attachments
modify_event: Update existing events
delete_event: Remove events

Google Drive

search_drive_files: Search files with query syntax
get_drive_file_content: Read file content (supports Office formats)
list_drive_items: List folder contents
create_drive_file: Create new files or fetch from URLs

Gmail

search_gmail_messages: Search with Gmail operators
get_gmail_message_content: Retrieve message content
send_gmail_message: Send emails
draft_gmail_message: Create drafts

Google Docs

search_docs: Find documents by name
get_doc_content: Extract document text
list_docs_in_folder: List docs in folder
create_doc: Create new documents
read_doc_comments: Read all comments and replies
create_doc_comment: Create new comments
reply_to_comment: Reply to existing comments
resolve_comment: Resolve comments

Google Sheets

list_spreadsheets: List accessible spreadsheets
get_spreadsheet_info: Get spreadsheet metadata
read_sheet_values: Read cell ranges
modify_sheet_values: Write/update/clear cells
create_spreadsheet: Create new spreadsheets
create_sheet: Add sheets to existing files
read_sheet_comments: Read all comments and replies
create_sheet_comment: Create new comments
reply_to_sheet_comment: Reply to existing comments
resolve_sheet_comment: Resolve comments

Google Slides

Various tools for creating and managing presentations and comments

Google Forms

Tools for creating forms, configuring settings, and managing responses

Google Tasks

Complete task management with lists, hierarchies, due dates, and status tracking

Google Chat

List spaces, retrieve messages, send messages, search chat history

Google Custom Search

Perform web searches using Programmable Search Engine

First-Time Authentication

When calling a tool:

Server returns authorization URL
Open URL in browser and authorize
Server handles OAuth callback automatically
Retry the original request

The server features transport-aware OAuth callback handling that works seamlessly in both stdio and HTTP modes.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "google_workspace" '{"command":"uvx","args":["workspace-mcp"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "google_workspace": {
            "command": "uvx",
            "args": [
                "workspace-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

{
    "mcpServers": {
        "google_workspace": {
            "command": "uvx",
            "args": [
                "workspace-mcp"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect