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

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

Usage

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

MIT License - see LICENSE file for details