aaronsb google workspace mcp

WHAT IT CONNECTS

aaronsb google workspace mcp 为 AI Agent 提供什么

• Simplified attachment handling with automatic metadata management
• Streamlined email responses focused on essential information
• Robust attachment indexing and retrieval system
• Efficient file management across Gmail and Calendar
• Automatic cleanup of expired attachments
• `list_workspace_accounts` (aliases: list_accounts, get_accounts, show_accounts)
• List all configured Google accounts and authentication status
• Must be called first before other operations
• Validates required API scopes
• Handles multiple account selection
• `authenticate_workspace_account` (aliases: auth_account, add_account, connect_account)
• Add and authenticate Google accounts for API access
• Supports account categorization (work, personal)
• Handles OAuth flow with user interaction
• Manages token refresh automatically
• `remove_workspace_account` (aliases: delete_account, disconnect_account, remove_account)
• Remove Google accounts and associated tokens
• Clean up stored credentials
• `search_workspace_emails` (aliases: search_emails, find_emails, query_emails)
• Advanced email filtering capabilities:
• Sender/recipient filtering
• Subject and content search
• Date range filtering
• Attachment presence
• Label-based filtering
• Complex Gmail query syntax support
• Common search patterns for:
• Meeting emails
• HR/Admin communications
• Team updates
• Newsletters
• `send_workspace_email` (aliases: send_email, send_mail, create_email)
• Send emails with full formatting
• Support for CC/BCC recipients
• Attachment handling
• Email threading support
• `get_workspace_gmail_settings` (aliases: get_gmail_settings, gmail_settings, get_mail_settings)
• Access account settings
• Language preferences
• Signature configuration
• Vacation responder status
• Filter and forwarding rules
• `manage_workspace_draft` (aliases: manage_draft, draft_operation, handle_draft)
• Complete draft CRUD operations:
• Create new drafts
• Read existing drafts
• Update draft content
• Delete drafts
• Send drafts
• Support for:
• New email drafts
• Reply drafts with threading
• Draft modifications
• Draft sending
• `manage_workspace_label` (aliases: manage_label, label_operation, handle_label)
• Full label CRUD operations
• Support for nested labels
• Custom color configuration
• Visibility settings
• `manage_workspace_label_assignment` (aliases: assign_label, modify_message_labels, change_message_labels)
• Apply/remove labels from messages
• Batch label modifications
• System label updates
• `manage_workspace_label_filter` (aliases: manage_filter, handle_filter, filter_operation)
• Create and manage label filters
• Complex filtering criteria:
• Sender/recipient patterns
• Subject/content matching
• Attachment presence
• Message size rules
• Automated actions:
• Label application
• Importance marking
• Read status
• Archiving
• `list_workspace_calendar_events` (aliases: list_events, get_events, show_events)
• List calendar events with filtering
• Date range specification
• Text search within events
• Customizable result limits
• `get_workspace_calendar_event` (aliases: get_event, view_event, show_event)
• Detailed event information
• Attendee status
• Event settings
• `manage_workspace_calendar_event` (aliases: manage_event, update_event, respond_to_event)
• Event response management:
• Accept/Decline invitations
• Mark as tentative
• Propose new times
• Update event times
• Comment support
• Time zone handling
• `create_workspace_calendar_event` (aliases: create_event, new_event, schedule_event)
• Create new calendar events
• Support for:
• Single events
• Recurring events (RRULE format)
• Multiple attendees
• Time zone specification
• Event description
• Conflict checking
• `delete_workspace_calendar_event` (aliases: delete_event, remove_event, cancel_event)
• Delete calendar events
• Notification options for attendees
• `get_workspace_contacts` (aliases: get_contacts, list_contacts, fetch_contacts)
• Retrieve contacts from a Google account
• Support for:
• Basic contact information (names, emails, phones)
• Extended contact details
• Pagination for large contact lists
• Common use cases:
• Contact lookup
• Address book management
• Contact information retrieval
• `list_drive_files` (aliases: list_files, get_files, show_files)
• List files with optional filtering
• Filter by folder
• Custom query support
• Sorting and pagination
• Field selection
• `search_drive_files` (aliases: search_files, find_files, query_files)
• Full text search across file content
• Filter by MIME type
• Filter by folder
• Include/exclude trashed files
• Advanced query options
• `upload_drive_file` (aliases: upload_file, create_file, add_file)
• Upload new files
• Set file metadata
• Specify parent folders
• Support for various file types
• `download_drive_file` (aliases: download_file, get_file_content, fetch_file)
• Download any file type
• Export Google Workspace files
• Format conversion options
• Automatic MIME type handling
• `delete_drive_file` (aliases: delete_file, remove_file, trash_file)
• Delete files and folders
• Clean removal from Drive
• `create_drive_folder` (aliases: create_folder, new_folder, add_folder)
• Create new folders
• Nested folder support
• Parent folder specification
• Folder metadata
• `update_drive_permissions` (aliases: share_file, update_sharing, modify_permissions)
• Update sharing settings
• Multiple permission types:
• User permissions
• Group permissions
• Domain sharing
• Public access
• Various access roles:
• Owner
• Organizer
• File Organizer
• Writer
• Commenter
• Reader
• Discovery settings for public files
• Admin SDK support
• Additional Google services
• **Simplified Mocking**
• Use static mock responses for predictable testing
• Avoid complex end-to-end simulations in unit tests
• Focus on testing one piece of functionality at a time
• Mock external dependencies (OAuth, file system) with simple implementations
• **Test Organization**
• Group tests by functionality (e.g., account operations, file operations)
• Use clear, descriptive test names
• Keep tests focused and isolated
• Reset mocks and modules between tests
• **Mock Management**
• Use jest.resetModules() to ensure clean state
• Re-require modules after mock changes
• Track mock function calls explicitly
• Verify both function calls and results
• **File System Testing**
• Use simple JSON structures
• Focus on data correctness over formatting
• Test error scenarios (missing files, invalid JSON)
• Verify file operations without implementation details
• **Token Handling**
• Mock token validation with static responses
• Test success and failure scenarios separately
• Verify token operations without OAuth complexity
• Focus on account manager's token handling logic
• **Authentication**
• Store credentials securely in MCP settings
• Use minimal required scopes
• Handle token refresh properly
• **Error Handling**
• Check response status
• Handle auth errors appropriately
• Implement proper retries
• **Configuration & Security**
• Each user maintains their own Google Cloud Project
• Configure OAuth credentials in MCP settings
• Secure token storage in ~/.mcp/google-workspace-mcp
• Regular token rotation
• Never commit sensitive files to git
• Use proper file permissions for config directory
• **Local Development Setup**
• Configure OAuth credentials in MCP settings
• Create ~/.mcp/google-workspace-mcp directory
• Keep sensitive tokens out of version control
• Run authentication script for each account
• **Missing Configuration**
• Error: "GOOGLE_CLIENT_ID environment variable is required"
• Solution: Configure the OAuth credentials in your MCP settings file (see docs/API.md for details)
• **Authentication Errors**
• Error: "Invalid OAuth credentials"
• Solution:
• Verify your Google Cloud project is properly configured
• Ensure you've added yourself as a test user in the OAuth consent screen
• Check that both Gmail API and Google Calendar API are enabled
• Verify credentials in MCP settings match your OAuth client configuration
• **Token Issues**
• Error: "Token refresh failed"
• Solution: Remove the account using `remove_workspace_account` and re-authenticate
• Check that your Google Cloud project has the necessary API scopes enabled
• **Directory Structure**
• Error: "Directory not found"
• Solution: Ensure ~/.mcp/google-workspace-mcp exists with proper permissions
• Verify Docker has access to mount the config directory