Mcp 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

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

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

1. Install dependencies:

``bash npm install ``

1. Build the TypeScript code:

``bash 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)

1. Required OAuth2 Scopes:

``json [ "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" ] ``

1. 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"] } } ``

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

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

Development/Unpublished Servers Configuration

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

Published Servers Configuration

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

``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)

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

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

1. gmail_get_email

• Retrieve complete email content by ID
• Includes full message body and attachment info

1. gmail_bulk_get_emails

• Retrieve multiple emails by ID in a single request
• Efficient for batch processing

1. gmail_create_draft

• Create new email drafts
• Support for CC recipients

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

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

1. gmail_reply

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

1. gmail_get_attachment

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

1. gmail_bulk_save_attachments

• Save multiple attachments in a single operation

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

1. calendar_get_events

• Retrieve events in a date range
• Support for multiple calendars
• Filter options (deleted events, max results)
• Timezone customization

1. calendar_create_event

• Create new calendar events
• Support for attendees and notifications
• Location and description fields
• Timezone handling

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: j3k0
• Source: j3k0/mcp-google-workspace
• License: MIT

Install and usage instructions live in the source repository linked above.