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
π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
-
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
-
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)
-
Restart Cline/Claude
-
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
-
Authentication:
Store credentials securely, use minimal scopes, handle token refresh. -
Error Handling:
Check statuses, handle auth errors, implement retries. -
Configuration & Security:
Each user should use their own Google Cloud Project.
Secure token storage and avoid committing sensitive files. -
Local Development:
Configure OAuth credentials properly, keep tokens out of version control, authenticate each account.
Troubleshooting
Common Issues
-
Missing Configuration:
Error about missingGOOGLE_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