MCP Google Workspace Server

A Model Context Protocol server for Google Workspace services. This server provides tools to interact with Gmail and Google Calendar through the MCP protocol.

Features

Multiple Google Account Support
Use and switch between multiple Google accounts
Each account can have custom metadata and descriptions
Gmail Integration
Query emails with advanced search
Read full email content and attachments
Create and manage drafts
Reply to emails
Archive emails
Handle attachments
Bulk operations support
Calendar Integration
List available calendars
View calendar events
Create new events
Delete events
Support for multiple calendars
Custom timezone support

Example Prompts

Try these example prompts with your AI assistant:

Gmail

"Retrieve my latest unread messages"
"Search my emails from the Scrum Master"
"Retrieve all emails from accounting"
"Take the email about ABC and summarize it"
"Write a nice response to Alice's last email and upload a draft"
"Reply to Bob's email with a Thank you note. Store it as draft"

Calendar

"What do I have on my agenda tomorrow?"
"Check my private account's Family agenda for next week"
"I need to plan an event with Tim for 2hrs next week. Suggest some time slots"

Prerequisites

Node.js >= 18
A Google Cloud project with Gmail and Calendar APIs enabled
OAuth 2.0 credentials for Google APIs

Installation

Clone the repository: bash git clone https://github.com/j3k0/mcp-google-workspace.git cd mcp-google-workspace
Install dependencies: bash npm install
Build the TypeScript code: bash npm run build

Configuration

OAuth 2.0 Setup

Google Workspace (G Suite) APIs require OAuth2 authorization. Follow these steps to set up authentication:

Create OAuth2 Credentials:
Go to the Google Cloud Console
Create a new project or select an existing one
Enable the Gmail API and Google Calendar API for your project
Go to "Credentials" → "Create Credentials" → "OAuth client ID"
Select "Desktop app" or "Web application" as the application type
Configure the OAuth consent screen with required information
Add authorized redirect URIs (include http://localhost:4100/code for local development)
Required OAuth2 Scopes: json [ "openid", "https://mail.google.com/", "https://www.googleapis.com/auth/calendar", "https://www.googleapis.com/auth/userinfo.email" ]
Create a .gauth.json file in the project root with your Google OAuth 2.0 credentials: json { "installed": { "client_id": "your_client_id", "project_id": "your_project_id", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://oauth2.googleapis.com/token", "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "client_secret": "your_client_secret", "redirect_uris": ["http://localhost:4100/code"] } }
Create a .accounts.json file to specify which Google accounts can use the server: json { "accounts": [ { "email": "your.email@gmail.com", "account_type": "personal", "extra_info": "Primary account with Family Calendar" } ] }

You can specify multiple accounts. Make sure they have access in your Google Auth app. The extra_info field is especially useful as you can add information here that you want to tell the AI about the account (e.g., whether it has a specific calendar).

Claude Desktop Configuration

Configure Claude Desktop to use the mcp-google-workspace server:

On MacOS: Edit ~/Library/Application\ Support/Claude/claude_desktop_config.json

On Windows: Edit %APPDATA%/Claude/claude_desktop_config.json

Development/Unpublished Servers Configuration

{
  "mcpServers": {
    "mcp-google-workspace": {
      "command": "<dir_to>/mcp-google-workspace/launch"
    }
  }
}

Published Servers Configuration

{
  "mcpServers": {
    "mcp-google-workspace": {
      "command": "npx",
      "args": [
        "mcp-google-workspace"
      ]
    }
  }
}

Usage

Start the server: bash npm start

Optional arguments: - --gauth-file: Path to the OAuth2 credentials file (default: ./.gauth.json) - --accounts-file: Path to the accounts configuration file (default: ./.accounts.json) - --credentials-dir: Directory to store OAuth credentials (default: current directory)

The server will start and listen for MCP commands via stdin/stdout.
On first run for each account, it will:
Open a browser window for OAuth2 authentication
Listen on port 4100 for the OAuth2 callback
Store the credentials for future use in a file named .oauth2.{email}.json

Available Tools

Account Management

gmail_list_accounts / calendar_list_accounts
List all configured Google accounts
View account metadata and descriptions
No user_id required

Gmail Tools

gmail_query_emails
Search emails with Gmail's query syntax (e.g., 'is:unread', 'from:example@gmail.com', 'newer_than:2d', 'has:attachment')
Returns emails in reverse chronological order
Includes metadata and content summary
gmail_get_email
Retrieve complete email content by ID
Includes full message body and attachment info
gmail_bulk_get_emails
Retrieve multiple emails by ID in a single request
Efficient for batch processing
gmail_create_draft
Create new email drafts
Support for CC recipients
gmail_delete_draft
Delete draft emails by ID
gmail_reply
Reply to existing emails
Option to send immediately or save as draft
Support for "Reply All" via CC
gmail_get_attachment
Download email attachments
Save to disk or return as embedded resource
gmail_bulk_save_attachments
Save multiple attachments in a single operation
gmail_archive / gmail_bulk_archive
Move emails out of inbox
Support for individual or bulk operations

Calendar Tools

calendar_list
List all accessible calendars
Includes calendar metadata, access roles, and timezone information
calendar_get_events
Retrieve events in a date range
Support for multiple calendars
Filter options (deleted events, max results)
Timezone customization
calendar_create_event
Create new calendar events
Support for attendees and notifications
Location and description fields
Timezone handling
calendar_delete_event
Delete events by ID
Option for cancellation notifications

Development

Source code is in TypeScript under the src/ directory
Build output goes to dist/ directory
Uses ES modules for better modularity
Follows Google API best practices

Project Structure

mcp-google-workspace/
├── src/
│   ├── server.ts           # Main server implementation
│   ├── services/
│   │   └── gauth.ts        # Google authentication service
│   ├── tools/
│   │   ├── gmail.ts        # Gmail tools implementation
│   │   └── calendar.ts     # Calendar tools implementation
│   └── types/
│       └── tool-handler.ts # Common types and interfaces
├── .gauth.json             # OAuth2 credentials
├── .accounts.json          # Account configuration
├── package.json            # Project dependencies
└── tsconfig.json           # TypeScript configuration