MCP HubMCP Hub
aaronsb

google-workspace-mcp

by: aaronsb

A Model Context Protocol (MCP) server that provides authenticated access to Google Workspace APIs, offering integrated Authentication, Gmail, Calendar, and Drive functionality

40created 27/01/2025
Visit
Google
API

📌Overview

Purpose: This framework allows users to seamlessly manage their Google Workspace account through a Model Context Protocol (MCP) server, enhancing productivity by simplifying interaction with services like Gmail, Calendar, and Drive.

Overview: The Google Workspace MCP Server provides a user-friendly interface to access and manage Google Workspace features. After a straightforward setup process, users gain enhanced control over their email, calendar, and files without dealing with cumbersome login protocols or manual organization.

Key Features:

  • Email Management: Automates sorting and labeling of emails, enables quick searches for specific messages, and simplifies attachment handling, making inbox management efficient and intuitive.

  • Calendar Optimization: Effectively schedules meetings by identifying open time slots, handles recurring events, and automates rescheduling, thereby reducing scheduling conflicts and improving time management.

  • Drive Organization: Transforms Google Drive into an organized workspace, allowing users to easily manage file sharing, search content within files, and streamline file storage across user accounts.

Google Workspace MCP Server

This Model Context Protocol (MCP) server gives you control of your Google Workspace. Once you connect your account through a simple, secure process, it keeps your connection safe and active, allowing you to focus on productivity instead of managing logins and permissions.

Key Features

  • Manage your Gmail inbox efficiently with smart sorting, labels, filters, and easy attachment handling.
  • Use your calendar to avoid scheduling conflicts, plan meetings, and handle recurring events effortlessly.
  • Organize Google Drive files and folders with precise sharing controls and powerful search capabilities.

TL;DR Setup

  1. Create Google Cloud Project:

    • Go to Google Cloud Console
    • Create Project
    • Enable Gmail API and Calendar API
    • Configure OAuth consent screen (External)
    • Create OAuth Desktop Client ID and Secret

  2. Add to Cline settings (example):

    {
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v", "/home/aaron/.mcp/google-workspace-mcp:/app/config",
        "-v", "/home/aaron/Documents/workspace-mcp-files:/app/workspace",
        "-e", "GOOGLE_CLIENT_ID",
        "-e", "GOOGLE_CLIENT_SECRET",
        "-e", "LOG_MODE=strict",
        "ghcr.io/aaronsb/google-workspace-mcp:latest"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      },
      "autoApprove": [],
      "disabled": false
    }
  }
}

    Logging modes available:

    • normal (default)
    • strict (routes all non-JSON-RPC messages to stderr; recommended for Claude desktop)

  3. Restart Cline/Claude

  4. Authenticate:
    Ask the AI to "add my Google account" and follow the conversational guide to authenticate.

Prerequisites

  • Create a Google Cloud Project at Google Cloud Console.
  • Enable:
    • Gmail API
    • Google Calendar API
    • Google Drive API
  • Configure OAuth consent screen as External; add yourself as a test user.
  • Create OAuth 2.0 Desktop credentials; note your Client ID and Secret.
  • Use "urn:ietf:wg:oauth:2.0:oob" as redirect URI for out-of-band authentication.
  • Prepare a local directory for storing configuration (recommended: ~/.mcp/google-workspace-mcp).

The server uses out-of-band authentication, requiring manual copy-pasting of authorization codes during the first setup for each account.

Using with Cline

Add the MCP server configuration to your Cline settings as shown in the TL;DR setup.

File Management

Workspace files are organized automatically:

~/Documents/workspace-mcp-files/
├── [email_1@domain.com]/
│   ├── downloads/      # Files downloaded from Drive
│   └── uploads/        # Files staged for upload
├── [email_2@domain.com]/
│   ├── downloads/
│   └── uploads/
└── shared/
    └── temp/          # Temporary files (auto-cleaned)
  • The WorkspaceManager:
    • Creates directories as needed
    • Organizes files by user email
    • Cleans up temporary files
    • Maintains proper file permissions

You can customize the workspace path by setting the WORKSPACE_BASE_PATH environment variable.

Manual Usage

Important: Ensure an accounts.json file exists in the config directory; copy accounts.example.json to accounts.json on initial setup.

Run the container directly:

docker run -i --rm \
  -v ~/.mcp/google-workspace-mcp:/app/config \
  -v ~/Documents/workspace-mcp-files:/app/workspace \
  -e GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com \
  -e GOOGLE_CLIENT_SECRET=your-client-secret \
  -e LOG_MODE=strict \
  ghcr.io/aaronsb/google-workspace-mcp:latest

The server manages configuration files, securely stores credentials, and handles permissions automatically.

Development Build

Local Build Script

Run the local build pipeline (installs, lints, tests, builds Docker image):

./scripts/build-local.sh

Options:

  • --verbose for detailed logs
  • --tag my-custom-tag to set a custom Docker image tag

Logs are saved under /tmp/google-workspace-mcp/.

The build uses Dockerfile.local, optimized for local development without specialized platform settings.

Manual Docker Build

Build and run the container manually:

docker build -t google-workspace-mcp:local .

# or with local development Dockerfile:
docker build -t google-workspace-mcp:local -f Dockerfile.local .

docker run -i --rm \
  -v ~/.mcp/google-workspace-mcp:/app/config \
  -v ~/Documents/workspace-mcp-files:/app/workspace \
  -e GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com \
  -e GOOGLE_CLIENT_SECRET=your-client-secret \
  -e LOG_MODE=strict \
  google-workspace-mcp:local

Features Summary

  • Automatic, simplified attachment handling with metadata management.
  • Streamlined handling of email responses.
  • Robust attachment indexing and retrieval.
  • Efficient file management across Gmail and Calendar.
  • Automatic cleanup of expired attachments.

Available Tools

Account Management

  • list_workspace_accounts
    List configured Google accounts, validate scopes, and handle multiple account selections.

  • authenticate_workspace_account
    Add and authenticate accounts, support categorization, OAuth flow, and token refresh.

  • remove_workspace_account
    Remove accounts and clean stored credentials.

Gmail Operations

Messages and Search

  • search_workspace_emails
    Advanced search by sender/recipient, subject, date, attachments, labels, and Gmail query syntax.

  • send_workspace_email
    Send formatted emails with CC/BCC, attachments, and threading.

Settings and Configuration

  • get_workspace_gmail_settings
    Access language, signature, vacation responders, filters, and forwarding rules.

Draft Management

  • manage_workspace_draft
    Create, read, update, delete, and send drafts including replies with threading.

Label Management

  • manage_workspace_label
    Full CRUD for labels, nested labels, colors, and visibility.

  • manage_workspace_label_assignment
    Apply/remove labels from messages in batches.

  • manage_workspace_label_filter
    Create/manage filters with complex criteria and automated actions.

Calendar Operations

Event Management

  • list_workspace_calendar_events
    List events with filtering on date and text.

  • get_workspace_calendar_event
    Retrieve detailed event info including attendees.

  • manage_workspace_calendar_event
    Respond to events, propose times, comment, and handle time zones.

  • create_workspace_calendar_event
    Create single or recurring events with attendees and conflict checking.

  • delete_workspace_calendar_event
    Delete events with attendee notification options.

Drive Operations

File Management

  • list_drive_files
    List files with filters, sorting, pagination, and field selection.

  • search_drive_files
    Full-text search with MIME type filtering and trashed files options.

  • upload_drive_file
    Upload files with metadata and parent folders.

  • download_drive_file
    Download any file, export Google Workspace formats with conversions.

  • delete_drive_file
    Delete files and folders cleanly.

Folder Operations

  • create_drive_folder
    Create nested folders with metadata.

Permissions

  • update_drive_permissions
    Manage sharing settings with various permission types and roles.

Refer to the API Documentation for detailed usage.

Coming Soon

  • Admin SDK support
  • Additional Google services integration

Testing Strategy

Unit Testing Approach

  • Use static mocks for predictable testing.
  • Organize tests by feature.
  • Mock external dependencies simply.
  • Use jest.resetModules() for clean test states.
  • Track mock calls and results carefully.
  • Test file system operations focusing on data correctness.
  • Mock token handling and verify both success and failure cases.

Running Tests

# Run all tests
npm test

# Run a specific test file
npm test path/to/test.ts

# Run tests with coverage
npm test -- --coverage

# CI runs tests with coverage reporting
npm run test:ci

Best Practices

  1. Authentication:
    Store credentials securely, use minimal scopes, handle token refresh.

  2. Error Handling:
    Check statuses, handle auth errors, implement retries.

  3. Configuration & Security:
    Each user should use their own Google Cloud Project.
    Secure token storage and avoid committing sensitive files.

  4. Local Development:
    Configure OAuth credentials properly, keep tokens out of version control, authenticate each account.

Troubleshooting

Common Issues

  • Missing Configuration:
    Error about missing GOOGLE_CLIENT_ID? Configure OAuth credentials in MCP settings.

  • Authentication Errors:
    Verify project configuration, test user setup, API enablement, and credential correctness.

  • Token Issues:
    Remove and re-authenticate the account if token refresh fails. Confirm API scopes.

  • Directory Structure:
    Ensure config directory exists and Docker has access.

Refer to the Error Handling documentation for more help.

License

MIT License - See LICENSE file for details