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:

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

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

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