Google Workspace

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

Calendar

Prerequisites

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

Installation

1. Clone the repository:

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

   cd mcp-google-workspace

   

2. Install dependencies:

   npm install

   

3. 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:

1. 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)

2. Required OAuth2 Scopes:

   [

     "openid",

     "https://mail.google.com/",

     "https://www.googleapis.com/auth/gmail.settings.basic",

     "https://www.googleapis.com/auth/calendar",

     "https://www.googleapis.com/auth/userinfo.email"

   ]

   

3. 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"]

     }

   }

   

4. Create a .accounts.json file to specify which Google accounts can use the server:

   {

     "accounts": [

       {

         "email": "[email protected]",

         "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).

Authenticate

Once .gauth.json and .accounts.json are configured, authenticate your accounts:

npm run authenticate

This opens a browser for each configured account to complete the OAuth consent flow. The script waits up to 5 minutes per account for the callback.

```bash