MCP Google Workspace Server

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

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

1. Clone the repository: ```bash git clone https://github.com/j3k0/mcp-google-workspace.git cd mcp-google-workspace ```

2. Install dependencies: ```bash npm install ```

3. Build the TypeScript code: ```bash npm run build ```

Configuration

OAuth 2.0 Setup

1. Create OAuth2 Credentials: - Go to the [Google Cloud Console](https://console.cloud.google.com/) - 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: ```json [ "openid", "https://mail.google.com/", "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: ```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"] } } ```

4. 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

Usage

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

2. The server will start and listen for MCP commands via stdin/stdout.

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

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

Gmail Tools

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

2. `gmail_get_email` - Retrieve complete email content by ID - Includes full message body and attachment info

3. `gmail_bulk_get_emails` - Retrieve multiple emails by ID in a single request - Efficient for batch processing

4. `gmail_create_draft` - Create new email drafts - Support for CC recipients

5. `gmail_delete_draft` - Delete draft emails by ID

6. `gmail_reply` - Reply to existing emails - Option to send immediately or save as draft - Support for "Reply All" via CC

7. `gmail_get_attachment` - Download email attachments - Save to disk or return as embedded resource

8. `gmail_bulk_save_attachments` - Save multiple attachments in a single operation

9. `gmail_archive` / `gmail_bulk_archive` - Move emails out of inbox - Support for individual or bulk operations

Calendar Tools

1. `calendar_list` - List all accessible calendars - Includes calendar metadata, access roles, and timezone information

2. `calendar_get_events` - Retrieve events in a date range - Support for multiple calendars - Filter options (deleted events, max results) - Timezone customization

3. `calendar_create_event` - Create new calendar events - Support for attendees and notifications - Location and description fields - Timezone handling

4. `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

Development Commands

• `npm run build`: Build TypeScript code

• `npm start`: Start the server

• `npm run dev`: Start in development mode with auto-reload

Contributing

1. Fork the repository

2. Create a feature branch

3. Commit your changes

4. Push to the branch

5. Create a Pull Request

License