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 >= 20
• A Google Cloud project with Gmail and Calendar APIs enabled
• OAuth 2.0 credentials for Google APIs

Installation

1. Clone the repository:

   hljs language-bash

   Copy

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

2. Install dependencies:

   hljs language-bash

   Copy

   npm install
   

3. Build the TypeScript code:

   hljs language-bash

   Copy

   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:

   hljs language-json

   Copy

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

   hljs language-json

   Copy

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

   hljs language-json

   Copy

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

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.

# Authenticate a specific account
npm run authenticate -- user@gmail.com

# Force re-authentication (e.g. after OAuth scope changes)
npm run authenticate -- user@gmail.com --force

# Custom config paths (same flags as the server)
npm run authenticate -- --gauth-file /path/to/.gauth.json --accounts-file /path/to/.accounts.json

If installed via npm, you can also run:

npx mcp-gmail-authenticate

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

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

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

Docker

You can also build and run the MCP server in Docker:

docker build -t mcp-google-workspace .
docker run --rm -i \
  -v "$PWD/.gauth.json:/app/.gauth.json:ro" \
  -v "$PWD/.accounts.json:/app/.accounts.json:ro" \
  -v "$PWD/.credentials:/app/.credentials" \
  -e GMAIL_ALLOW_DRAFTS=true \
  -e GMAIL_ATTACHMENTS_DIR=/app/attachments \
  mcp-google-workspace \
  node dist/server.js --credentials-dir /app/.credentials

Do not bake .gauth.json, .accounts.json, OAuth tokens, or .env files into the image. The included .dockerignore excludes those files; mount them at runtime instead.

Usage

1. Start the server:

   hljs language-bash

   Copy

   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

Environment Variables

• GMAIL_ALLOW_SENDING — set to true to allow gmail_send to actually send mail. Defaults to disabled.
• GMAIL_ALLOW_DRAFTS — set to true to allow draft creation tools. Defaults to disabled.
• GMAIL_ATTACHMENTS_DIR — base directory under which gmail_get_attachment and gmail_bulk_save_attachments may write files. Attachment paths supplied by the caller are treated as relative to this directory; absolute paths, traversal, and symlinks that escape the directory are rejected. Defaults to ~/.mcp-gsuite/attachments.

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 draft_id
   • Note: draft_id is distinct from the message ID returned by gmail_query_emails. Use gmail_list_drafts to obtain it.

6. gmail_list_drafts

   • List Gmail drafts, optionally filtered by a Gmail search query
   • Returns each draft's draft_id (required for gmail_delete_draft) alongside its message_id, subject, recipients, and snippet

7. gmail_reply

   • Reply to existing emails
   • Option to send immediately or save as draft
   • Support for "Reply All" via CC

8. gmail_get_attachment

   • Download email attachments
   • Save to disk or return as embedded resource

9. gmail_bulk_save_attachments

   • Save multiple attachments in a single operation

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

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

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT License - see LICENSE file for details