📌Overview

Purpose: To provide a Model Context Protocol server for seamless interaction with Google Workspace services, primarily Gmail and Google Calendar.

Overview: The MCP Google Workspace Server enables users to manage multiple Google accounts and efficiently interact with Gmail and Google Calendar using the MCP protocol. It supports advanced functionalities such as email querying, event management, and bulk operations, catering to diverse user needs.

Key Features:

Multiple Google Account Support: Allows users to manage and switch between multiple Google accounts, each with custom metadata for easy identification.
Gmail Integration: Provides a suite of tools to search, read, manage, and perform bulk operations on emails, making email handling efficient and organized.
Calendar Integration: Facilitates event management by listing available calendars, creating and deleting events, and supporting multiple calendars and custom time zones for better organization of schedules.

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 and 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:

git clone https://github.com/j3k0/mcp-google-workspace.git
cd mcp-google-workspace

Install dependencies:
```
npm install
```
Build the TypeScript code:
```
npm run build
```

Configuration

OAuth 2.0 Setup

Google Workspace APIs require OAuth2 authorization:

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
- Add authorized redirect URIs (include http://localhost:4100/code for local development)

Required OAuth2 Scopes:

[
  "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:

{
  "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:

{
  "accounts": [
    {
      "email": "your.email@gmail.com",
      "account_type": "personal",
      "extra_info": "Primary account with Family Calendar"
    }
  ]
}

You can specify multiple accounts. The extra_info field is useful to tell the AI about the account features.

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:
```
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 listens for MCP commands via stdin/stdout.
On first run for each account, it:
- Opens a browser window for OAuth2 authentication
- Listens on port 4100 for the OAuth2 callback
- Stores credentials for future use in .oauth2.{email}.json

Available Tools

Account Management

gmail_list_accounts / calendar_list_accounts
List all configured Google accounts with metadata.

Gmail Tools

gmail_query_emails
Search emails using Gmail's query syntax, returns emails in reverse chronological order with metadata and summaries.
gmail_get_email
Retrieve complete email content by ID including attachments.
gmail_bulk_get_emails
Retrieve multiple emails in a single request.
gmail_create_draft
Create new email drafts with CC support.
gmail_delete_draft
Delete drafts by ID.
gmail_reply
Reply to emails, option to send or save as draft, supports "Reply All" via CC.
gmail_get_attachment
Download email attachments, save to disk or embed.
gmail_bulk_save_attachments
Save multiple attachments in one operation.
gmail_archive / gmail_bulk_archive
Archive emails individually or in bulk.

Calendar Tools

calendar_list
List all accessible calendars with metadata, access roles, and timezone info.
calendar_get_events
Retrieve events in a date range, supports multiple calendars, filtering, and timezone customization.
calendar_create_event
Create new events with attendees, notifications, location, description, and timezone support.
calendar_delete_event
Delete events by ID, optionally send cancellation notifications.

Development

Source code in TypeScript under src/
Build output in dist/
Uses ES modules
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

Development Commands

npm run build: Build TypeScript code
npm start: Start the server
npm run dev: Start in development mode with auto-reload

Contributing

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a Pull Request

License

MIT License - see LICENSE file for details