Google Workspace MCP Server

A Model Context Protocol (MCP) server providing 240 tools for Google Workspace: Gmail, Drive, Docs, Slides, Sheets, Calendar, Contacts, and Tasks.

Built with googleapis and @modelcontextprotocol/sdk.

Features

Service	Tools	Highlights
Gmail	75	Send/read/reply/forward, drafts, labels, threads, attachments, filters, settings, S/MIME, CSE, delegates, watch, HTML link extraction
Drive	47	Search, CRUD, upload/download, export, trash, share, permissions, revisions, comments, replies, shared drives, labels, access proposals
Calendar	30	Events CRUD, search, quick add, import, recurring instances, free/busy, ACL, calendar management, watch, settings
Sheets	17	Read, write, create, append, clear, batch operations, data filters, developer metadata, copy sheet
Contacts	22	CRUD, batch operations, photos, contact groups, other contacts, directory search
Tasks	14	Tasks and task lists CRUD, complete, move/reorder, clear
Docs	7	Create, read, insert text/tables/images, batch update, find & replace
Slides	8	Create, read, add slides, get page, thumbnails, insert text, replace text, batch update

Prerequisites

• Node.js 18+
• A Google Cloud Platform project with OAuth 2.0 credentials (Desktop app type)
• The following APIs enabled:
  • Gmail API
  • Google Drive API
  • Google Docs API
  • Google Slides API
  • Google Sheets API
  • Google Calendar API
  • People API (Contacts)
  • Tasks API

Quick Install

git clone https://github.com/salviz/google-mcp-server.git
cd google-mcp-server
npm install

Register with Claude Code

CLI:

claude mcp add google-workspace -- node /path/to/google-mcp-server/index.js

Or add to your MCP config (~/.claude/claude_desktop_config.json or .mcp.json):

{
  "mcpServers": {
    "google-workspace": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/google-mcp-server/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_TOKEN_PATH": "/path/to/credentials.json"
      }
    }
  }
}

Environment Variables

Variable	Required	Description
GOOGLE_CLIENT_ID	Yes	OAuth 2.0 client ID
GOOGLE_CLIENT_SECRET	Yes	OAuth 2.0 client secret
GOOGLE_TOKEN_PATH	No	Path to token JSON file (default: ~/.google-mcp/credentials.json)
GOOGLE_TOKEN_SECRET	No	Google Secret Manager secret name for token fallback (default: google-mcp-oauth-tokens)

Token File Format

{
  "access_token": "ya29...",
  "refresh_token": "1//...",
  "token_type": "Bearer",
  "expiry_date": 1700000000000
}

The server automatically refreshes expired tokens and persists updates to disk. If Google Cloud Secret Manager is available, tokens are also stored there as a cross-session fallback.

Tools (240)

Gmail (75)

Tool	Description
gmail_profile	Get Gmail profile info (email, messages/threads total, history ID)
gmail_send	Send a new email (plain text or HTML)
gmail_read	Read a message with full body text, HTML link extraction, and attachment info
gmail_reply	Reply to a message (keeps thread)
gmail_forward	Forward a message to another recipient
gmail_list	List recent messages
gmail_search	Search messages using Gmail query syntax
gmail_mark_read	Mark a message as read
gmail_mark_unread	Mark a message as unread
gmail_modify_labels	Add or remove labels from a message
gmail_trash	Move a message to trash
gmail_untrash	Remove a message from trash
gmail_delete	Permanently delete a message
gmail_batch_modify	Modify labels on multiple messages at once
gmail_batch_delete	Permanently delete multiple messages
gmail_insert_message	Insert a message directly into the mailbox
gmail_import_message	Import a message (similar to receiving via SMTP)
gmail_get_attachment	Download an attachment from a message
gmail_list_threads	List message threads
gmail_get_thread	Get all messages in a thread
gmail_thread_modify	Modify labels on a thread
gmail_thread_trash	Move a thread to trash
gmail_thread_untrash	Restore a thread from trash
gmail_thread_delete	Permanently delete a thread
gmail_create_draft	Create a new draft
gmail_list_drafts	List all drafts
gmail_get_draft	Get a specific draft
gmail_update_draft	Update an existing draft
gmail_delete_draft	Delete a draft
gmail_send_draft	Send a draft
gmail_list_labels	List all labels
gmail_get_label	Get a specific label
gmail_create_label	Create a new label
gmail_update_label	Update a label
gmail_delete_label	Delete a label
gmail_list_history	List mailbox changes since a history ID
gmail_get_auto_forwarding	Get auto-forwarding settings
gmail_update_auto_forwarding	Update auto-forwarding settings
gmail_get_imap	Get IMAP settings
gmail_update_imap	Update IMAP settings
gmail_get_pop	Get POP settings
gmail_update_pop	Update POP settings
gmail_get_language	Get language settings
gmail_update_language	Update language settings
gmail_get_vacation	Get vacation responder settings
gmail_update_vacation	Update vacation responder settings
gmail_list_send_as	List send-as aliases
gmail_get_send_as	Get a send-as alias
gmail_create_send_as	Create a send-as alias
gmail_update_send_as	Update a send-as alias
gmail_delete_send_as	Delete a send-as alias
gmail_verify_send_as	Send verification for a send-as alias
gmail_list_filters	List email filters
gmail_get_filter	Get a specific filter
gmail_create_filter	Create a new filter
gmail_delete_filter	Delete a filter
gmail_list_forwarding_addresses	List forwarding addresses
gmail_get_forwarding_address	Get a forwarding address
gmail_create_forwarding_address	Create a forwarding address
gmail_delete_forwarding_address	Delete a forwarding address
gmail_list_delegates	List mail delegates
gmail_get_delegate	Get a mail delegate
gmail_create_delegate	Create a mail delegate
gmail_delete_delegate	Delete a mail delegate
gmail_list_smime	List S/MIME certificates
gmail_get_smime	Get an S/MIME certificate
gmail_insert_smime	Insert an S/MIME certificate
gmail_delete_smime	Delete an S/MIME certificate
gmail_set_default_smime	Set default S/MIME certificate
gmail_list_cse_identities	List CSE identities
gmail_get_cse_identity	Get a CSE identity
gmail_create_cse_identity	Create a CSE identity
gmail_patch_cse_identity	Patch a CSE identity
gmail_delete_cse_identity	Delete a CSE identity
gmail_list_cse_keypairs	List CSE key pairs
gmail_get_cse_keypair	Get a CSE key pair
gmail_create_cse_keypair	Create a CSE key pair
gmail_enable_cse_keypair	Enable a CSE key pair
gmail_disable_cse_keypair	Disable a CSE key pair
gmail_obliterate_cse_keypair	Permanently delete a CSE key pair
gmail_watch	Set up push notifications via Pub/Sub
gmail_stop_watch	Stop push notifications

Google Drive (47)

Tool	Description
drive_search	Search files using Drive query syntax
drive_read	Read file content (detects binary, suggests download)
drive_list	List files in a folder
drive_file_info	Get detailed file metadata
drive_create_folder	Create a new folder
drive_create_file	Create a new text file
drive_update_file	Update file name, content, or description
drive_delete	Permanently delete a file
drive_trash	Move a file to trash
drive_untrash	Restore a file from trash
drive_copy	Copy a file
drive_move	Move a file to a different folder
drive_share	Share a file (user, group, domain, or anyone)
drive_list_permissions	List sharing permissions
drive_get_permission	Get a specific permission
drive_update_permission	Update a sharing permission
drive_remove_permission	Remove a sharing permission
drive_about	Get storage quota and user info
drive_upload_file	Upload a binary file from local filesystem
drive_download_file	Download a file to local filesystem
drive_get_comments	List comments on a file
drive_get_comment	Get a specific comment
drive_add_comment	Add a comment to a file
drive_update_comment	Update a comment
drive_delete_comment	Delete a comment
drive_create_reply	Reply to a comment
drive_list_replies	List replies to a comment
drive_get_reply	Get a specific reply
drive_update_reply	Update a reply
drive_delete_reply	Delete a reply
drive_export_file	Export Google Workspace files (PDF, DOCX, CSV, etc.)
drive_get_revisions	List file revision history
drive_get_revision	Get a specific revision
drive_update_revision	Update revision metadata
drive_delete_revision	Delete a revision
drive_empty_trash	Permanently empty all trash
drive_get_changes_start_token	Get starting page token for changes
drive_list_changes	List file changes since a page token
drive_watch_file	Watch a file for changes (webhook)
drive_watch_changes	Watch for file changes (webhook)
drive_stop_channel	Stop a watch channel
drive_generate_ids	Generate file IDs for uploads
drive_list_labels	List labels on a file
drive_modify_labels	Modify labels on a file
drive_list_access_proposals	List access proposals for a file
drive_get_access_proposal	Get a specific access proposal
drive_resolve_access_proposal	Accept or deny an access proposal
drive_list_apps	List installed Drive apps
drive_get_app	Get a specific Drive app
drive_get_operation	Get a long-running operation status
drive_create_shared_drive	Create a shared drive
drive_list_shared_drives	List shared drives
drive_get_shared_drive	Get a shared drive
drive_update_shared_drive	Update a shared drive
drive_hide_shared_drive	Hide a shared drive
drive_unhide_shared_drive	Unhide a shared drive
drive_delete_shared_drive	Delete a shared drive

Google Calendar (30)

Tool	Description
calendar_list_events	List upcoming events with optional time range
calendar_search_events	Search events by text
calendar_create_event	Create an event (supports all-day)
calendar_update_event	Update an existing event
calendar_delete_event	Delete an event
calendar_get_event	Get detailed event info
calendar_move_event	Move event between calendars
calendar_quick_add	Create event from natural language
calendar_import_event	Import an event by iCal UID
calendar_recurring_instances	List instances of a recurring event
calendar_freebusy	Check free/busy time for calendars
calendar_list_calendars	List all accessible calendars
calendar_create_calendar	Create a new calendar
calendar_get_calendar	Get calendar details
calendar_update_calendar	Update calendar properties
calendar_delete_calendar	Delete a calendar
calendar_clear	Clear all events from a calendar
calendar_list_get	Get calendar list entry
calendar_list_update	Update calendar list entry
calendar_list_insert	Subscribe to a calendar
calendar_list_delete	Unsubscribe from a calendar
calendar_acl_list	List calendar access control rules
calendar_acl_get	Get a specific ACL rule
calendar_acl_insert	Add an ACL rule
calendar_acl_update	Update an ACL rule
calendar_acl_delete	Delete an ACL rule
calendar_get_colors	Get available calendar/event colors
calendar_list_settings	List all user settings
calendar_get_setting	Get a specific setting
calendar_acl_watch	Watch ACL changes (webhook)
calendar_watch_events	Watch event changes (webhook)
calendar_list_watch	Watch calendar list changes (webhook)
calendar_watch_settings	Watch settings changes (webhook)
calendar_stop_channel	Stop a watch channel

Google Sheets (17)

Tool	Description
sheets_read	Read data from a spreadsheet range
sheets_write	Write data to a range
sheets_create	Create a new spreadsheet
sheets_append	Append rows after existing data
sheets_clear	Clear values from a range
sheets_batch_clear	Clear multiple ranges at once
sheets_batch_get	Read multiple ranges at once
sheets_batch_update	Structural operations (add sheets, merge cells, charts)
sheets_batch_update_values	Write to multiple ranges at once
sheets_get_info	Get spreadsheet metadata
sheets_copy_sheet	Copy a sheet to another spreadsheet
sheets_get_by_data_filter	Get spreadsheet data using data filters
sheets_batch_get_by_data_filter	Get values using data filters
sheets_batch_update_values_by_data_filter	Update values using data filters
sheets_batch_clear_by_data_filter	Clear ranges using data filters
sheets_developer_metadata_search	Search developer metadata
sheets_developer_metadata_get	Get developer metadata by ID

Google Contacts (22)

Tool	Description
contacts_list	List contacts with optional search
contacts_get	Get a specific contact
contacts_create	Create a new contact
contacts_update	Update an existing contact
contacts_delete	Delete a contact
contacts_batch_create	Create multiple contacts at once
contacts_batch_update	Update multiple contacts at once
contacts_batch_get	Get multiple contacts at once
contacts_batch_delete	Delete multiple contacts at once
contacts_update_photo	Upload a contact photo
contacts_delete_photo	Delete a contact photo
contacts_groups_list	List contact groups
contacts_group_create	Create a contact group
contacts_group_get	Get a contact group
contacts_group_update	Update a contact group
contacts_group_delete	Delete a contact group
contacts_group_batch_get	Get multiple contact groups
contacts_group_modify_members	Add or remove members from a group
contacts_other_list	List "other contacts" (auto-saved)
contacts_other_search	Search other contacts
contacts_other_copy	Copy an other contact to my contacts
contacts_search_directory	Search organization directory (Workspace)
contacts_list_directory	List directory contacts (Workspace)

Google Tasks (14)

Tool	Description
tasks_list	List all task lists
tasks_get_list	Get a specific task list
tasks_create_list	Create a new task list
tasks_delete_list	Delete a task list
tasks_list_tasks	List tasks in a task list
tasks_get	Get a specific task
tasks_create	Create a new task
tasks_update	Update a task
tasks_complete	Mark a task as completed
tasks_delete	Delete a task
tasks_move	Move or reorder a task
tasks_clear	Clear completed tasks from a list

Google Docs (7)

Tool	Description
docs_create	Create a new document with optional content and folder
docs_read	Read full document content as plain text
docs_insert_text	Insert text at a position
docs_batch_update	Apply batch update requests
docs_insert_table	Insert a table
docs_insert_image	Insert an inline image from a URL
docs_find_replace	Find and replace text

Google Slides (8)

Tool	Description
slides_create	Create a new presentation
slides_read	Read all slide content
slides_add_slide	Add a new slide
slides_get_page	Get details of a specific slide
slides_get_thumbnail	Generate a thumbnail image URL for a slide
slides_insert_text	Insert text into a shape or text box
slides_replace_all_text	Find and replace text across all slides
slides_batch_update	Apply batch update requests

Setup Guide

1. Create a Google Cloud Project

Go to the Google Cloud Console and create or select a project.

2. Enable APIs

In APIs & Services > Library, enable: Gmail, Drive, Docs, Slides, Sheets, Calendar, People, and Tasks APIs.

3. Create OAuth 2.0 Credentials

1. Navigate to APIs & Services > Credentials
2. Click Create Credentials > OAuth client ID
3. Select Desktop app
4. Note the client_id and client_secret

4. Obtain Tokens

Use the included re-authorization helper:

GOOGLE_CLIENT_ID=your-client-id GOOGLE_CLIENT_SECRET=your-client-secret node reauth.js

This starts a local server, opens an auth URL, and saves tokens after you authorize.

Required OAuth scopes:

• https://www.googleapis.com/auth/gmail.modify
• https://www.googleapis.com/auth/gmail.settings.basic
• https://www.googleapis.com/auth/gmail.settings.sharing
• https://www.googleapis.com/auth/drive
• https://www.googleapis.com/auth/calendar
• https://www.googleapis.com/auth/contacts
• https://www.googleapis.com/auth/tasks
• https://www.googleapis.com/auth/documents
• https://www.googleapis.com/auth/spreadsheets
• https://www.googleapis.com/auth/presentations

5. Save Tokens

mkdir -p ~/.google-mcp
# Tokens are automatically saved to ~/.google-mcp/credentials.json by reauth.js

Testing

Run the comprehensive test suite (tests all 240 tools):

GOOGLE_CLIENT_ID=your-id GOOGLE_CLIENT_SECRET=your-secret node test-all.js

Project Structure

google-mcp-server/
  index.js              # Server entry point, registers all tool modules
  auth.js               # OAuth 2.0 client, token management, Secret Manager fallback
  reauth.js             # OAuth re-authorization helper
  test-all.js           # Comprehensive test suite for all 240 tools
  tools/
    gmail.js            # 75 Gmail tools
    drive.js            # 47 Google Drive tools
    docs.js             # 7 Google Docs tools
    slides.js           # 8 Google Slides tools
    calendar.js         # 30 Google Calendar tools
    extras.js           # 36 tools: Contacts (22), Tasks (14), Sheets (17 - in sheets section)
  package.json

Security

• No hardcoded credentials -- all secrets via environment variables
• Tokens stored locally -- never transmitted except to Google's OAuth APIs
• Automatic token refresh -- expired tokens refreshed silently
• Secret Manager fallback -- optionally stores tokens in Google Cloud Secret Manager for resilience
• Stdio transport only -- no network server exposed
• Token file parsing wrapped in try-catch for resilience

Dependencies

Package	Purpose
@modelcontextprotocol/sdk	MCP server framework
googleapis	Official Google APIs client
zod	Schema validation for tool parameters

License

MIT